Class Providers<P extends Provider<?>>

java.lang.Object
opennlp.tools.util.ext.Providers<P>
Type Parameters:
P - The SPI, a sub-interface of Provider.

public final class Providers<P extends Provider<?>> extends Object
Resolves the providers of one SPI.

The providers are looked up with ServiceLoader when an instance is created, so of(Class) belongs into the startup of an application rather than into a request, and a new instance is needed to see providers added later. Availability, support for a spec and the configuration are read on every call. Instances are thread-safe; the only state that changes is the set of failures already reported.

Keep the instance in a field owned by the application and not in a static field, since OpenNLP can be deployed in a class loader shared by several applications.

Resolution is steered by name through configurationKey(), disabledKey() and allowedKey(), and by the provider class itself through ofTrusted(Class, ClassLoader, Predicate).

Since:
3.0.0
See Also:
  • Field Details

  • Method Details

    • of

      public static <P extends Provider<?>> Providers<P> of(Class<P> spi)
      Looks the providers of an SPI up with the thread context class loader, or with the class loader of spi if the thread has none or if it cannot see spi. On a thread whose context class loader is not the application's, such as a thread of a pool or of a container, this finds the providers of the SPI's own class loader only, so a library or a framework integration captures the class loader at startup and calls of(Class, ClassLoader).
      Type Parameters:
      P - The SPI.
      Parameters:
      spi - The SPI. Must be a sub-interface of Provider.
      Returns:
      The providers of spi. Never null.
      Throws:
      IllegalArgumentException - Thrown if spi is null or not a sub-interface of Provider.
      ProviderResolutionException - Thrown if the configuration or the service files cannot be read.
    • of

      public static <P extends Provider<?>> Providers<P> of(Class<P> spi, ClassLoader loader)
      Looks the providers of an SPI up with a class loader.
      Type Parameters:
      P - The SPI.
      Parameters:
      spi - The SPI. Must be a sub-interface of Provider.
      loader - The class loader to look providers up with. Must not be null.
      Returns:
      The providers of spi. Never null.
      Throws:
      IllegalArgumentException - Thrown if an argument is null, or if spi is not a sub-interface of Provider.
      ProviderResolutionException - Thrown if the configuration or the service files cannot be read.
    • of

      public static <P extends Provider<?>> Providers<P> of(Class<P> spi, ClassLoader loader, UnaryOperator<String> configuration)
      Looks the providers of an SPI up with a class loader and reads the configuration keys from an application's own source instead of "META-INF/opennlp/providers.properties"<P extends Provider<?>> and the system properties. Applications that share a class loader hierarchy, such as several deployments in one server, use this to configure resolution per application.
      Type Parameters:
      P - The SPI.
      Parameters:
      spi - The SPI. Must be a sub-interface of Provider.
      loader - The class loader to look providers up with. Must not be null.
      configuration - Answers configurationKey(), disabledKey() and allowedKey() with the configured value or null. Must not be null, and must be thread-safe, cheap and free of side effects, as it is called on every resolution.
      Returns:
      The providers of spi. Never null.
      Throws:
      IllegalArgumentException - Thrown if an argument is null, or if spi is not a sub-interface of Provider.
      ProviderResolutionException - Thrown if the service files cannot be read.
    • ofTrusted

      public static <P extends Provider<?>> Providers<P> ofTrusted(Class<P> spi, ClassLoader loader, Predicate<Class<?>> trusted)
      Looks the providers of an SPI up with a class loader, using only the provider classes a predicate accepts, which lets an application decide by the code source, the module or the signers of a class instead of by its name.

      The predicate is applied to each provider class the configuration permits, after the class has been loaded and before it is initialized and instantiated, so a rejected provider runs neither its static initializer nor its constructor. The predicate must not initialize the class either. An exception from it ends the lookup.

      Type Parameters:
      P - The SPI.
      Parameters:
      spi - The SPI. Must be a sub-interface of Provider.
      loader - The class loader to look providers up with. Must not be null.
      trusted - Accepts the provider classes that may be used. Must not be null.
      Returns:
      The providers of spi. Never null.
      Throws:
      IllegalArgumentException - Thrown if an argument is null, or if spi is not a sub-interface of Provider.
      ProviderResolutionException - Thrown if the configuration or the service files cannot be read, or if trusted throws.
    • of

      public static <P extends Provider<?>> Providers<P> of(Class<P> spi, ClassLoader loader, UnaryOperator<String> configuration, Predicate<Class<?>> trusted)
      Type Parameters:
      P - The SPI.
      Parameters:
      spi - The SPI. Must be a sub-interface of Provider.
      loader - The class loader to look providers up with. Must not be null.
      configuration - Answers the configuration keys. Must not be null.
      trusted - Accepts the provider classes that may be used. Must not be null.
      Returns:
      The providers of spi. Never null.
      Throws:
      IllegalArgumentException - Thrown if an argument is null, or if spi is not a sub-interface of Provider.
      ProviderResolutionException - Thrown if the service files cannot be read, or if trusted throws.
    • configurationKey

      public String configurationKey()
      Returns:
      The configuration key that selects a provider by name for select(ProviderSpec): "opennlp.provider."<P extends Provider<?>> followed by the fully qualified name of the SPI. Never null.
    • disabledKey

      public String disabledKey()
      Returns:
      The configuration key that disables providers of this SPI, a comma separated list of provider names and provider class names: configurationKey() followed by ".disabled"<P extends Provider<?>>. A provider disabled by name is not resolved but stays listed by installed(). A provider disabled by class name is not instantiated at all, which needs the class name to be configured before the providers are looked up. Never null.
    • allowedKey

      public String allowedKey()
      Returns:
      The configuration key that limits which provider classes of this SPI may be used: configurationKey() followed by ".allowed"<P extends Provider<?>>. The value is a comma separated list of provider class names and of package prefixes, which end with a dot; an unset or blank value allows every provider, a value that holds only separators allows none. It matches class names, not their origin. Use ofTrusted(Class, ClassLoader, Predicate) to validate provider classes. Unlike the other keys it is read from a system property or from the source an application passes only, never from "META-INF/opennlp/providers.properties"<P extends Provider<?>>, which any jar can carry. Providers are checked against it before they are instantiated, so it has to be configured before the lookup. Never null.
    • installed

      public List<P> installed()
      Returns:
      The providers in lookup order, including unavailable ones and those disabled by name. Unmodifiable and never null.
    • byName

      public Optional<P> byName(String name)
      Resolves an available provider by name, unless the name is disabled. If several available providers have the name, the one with the highest priority is returned. The key from configurationKey() is not applied.
      Parameters:
      name - The case-sensitive provider name. Must not be null or blank.
      Returns:
      The provider, or Optional.empty() if the name is disabled or no available provider has it.
      Throws:
      IllegalArgumentException - Thrown if name is null or blank.
      AmbiguousProviderException - Thrown if several providers of that name have the highest priority.
    • supporting

      public List<P> supporting(ProviderSpec spec)
      Lists the available providers that support a spec, without the disabled ones. The key from configurationKey() is not applied.
      Parameters:
      spec - The spec. Must not be null.
      Returns:
      The providers ordered by descending priority, providers of equal priority in lookup order. Unmodifiable and never null.
      Throws:
      IllegalArgumentException - Thrown if spec is null.
    • select

      public P select(ProviderSpec spec)
      Resolves the provider for a spec. The candidates are the available providers that support spec and are not disabled. If the key from configurationKey() holds a nonblank value, only candidates with that name, surrounding whitespace ignored, remain. The candidate with the highest priority is returned.
      Parameters:
      spec - The spec. Must not be null.
      Returns:
      The provider. Never null.
      Throws:
      IllegalArgumentException - Thrown if spec is null.
      UnsatisfiedProviderException - Thrown if no candidate remains.
      AmbiguousProviderException - Thrown if several candidates have the highest priority.