Class Providers<P extends Provider<?>>
- Type Parameters:
P- The SPI, a sub-interface ofProvider.
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 Summary
FieldsModifier and TypeFieldDescriptionstatic final StringThe suffix of the configuration key that limits which provider classes may be used, seeallowedKey().static final StringThe resource read for configuration keys, once per lookup and class loader, encoded in UTF-8.static final StringThe prefix of the configuration key that selects a provider by name forselect(ProviderSpec).static final StringThe suffix of the configuration key that disables providers by name, seedisabledKey().static final StringThe key that orders several "META-INF/opennlp/providers.properties"<P extends Provider<?>> files,0by default. -
Method Summary
Modifier and TypeMethodDescriptionResolves an availableproviderby name, unless the name is disabled.Looks theprovidersof an SPI up with the thread context class loader, or with the class loader ofspiif the thread has none or if it cannot seespi.of(Class<P> spi, ClassLoader loader) Looks theprovidersof an SPI up with a class loader.of(Class<P> spi, ClassLoader loader, UnaryOperator<String> configuration) Looks theprovidersof 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.of(Class<P> spi, ClassLoader loader, UnaryOperator<String> configuration, Predicate<Class<?>> trusted) ofTrusted(Class<P> spi, ClassLoader loader, Predicate<Class<?>> trusted) Looks theprovidersof 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.select(ProviderSpec spec) supporting(ProviderSpec spec)
-
Field Details
-
CONFIGURATION_KEY_PREFIX
The prefix of the configuration key that selects a provider by name forselect(ProviderSpec). The full key is the prefix followed by the fully qualified name of the SPI, seeconfigurationKey().- See Also:
-
DISABLED_KEY_SUFFIX
The suffix of the configuration key that disables providers by name, seedisabledKey().- See Also:
-
ALLOWED_KEY_SUFFIX
The suffix of the configuration key that limits which provider classes may be used, seeallowedKey().- See Also:
-
CONFIGURATION_FILE
The resource read for configuration keys, once per lookup and class loader, encoded in UTF-8. Several files are merged by their "configuration.ordinal"<P extends Provider<?>>, so the highest one wins, and a system property of the same name wins over all of them. Every jar of the class loader can carry this file. In a native image it is read only when it is registered as a resource.- See Also:
-
ORDINAL_KEY
The key that orders several "META-INF/opennlp/providers.properties"<P extends Provider<?>> files,0by default.- See Also:
-
-
Method Details
-
of
Looks theprovidersof an SPI up with the thread context class loader, or with the class loader ofspiif the thread has none or if it cannot seespi. 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 callsof(Class, ClassLoader).- Type Parameters:
P- The SPI.- Parameters:
spi- The SPI. Must be a sub-interface ofProvider.- Returns:
- The providers of
spi. Nevernull. - Throws:
IllegalArgumentException- Thrown ifspiisnullor not a sub-interface ofProvider.ProviderResolutionException- Thrown if the configuration or the service files cannot be read.
-
of
Looks theprovidersof an SPI up with a class loader.- Type Parameters:
P- The SPI.- Parameters:
spi- The SPI. Must be a sub-interface ofProvider.loader- The class loader to look providers up with. Must not benull.- Returns:
- The providers of
spi. Nevernull. - Throws:
IllegalArgumentException- Thrown if an argument isnull, or ifspiis not a sub-interface ofProvider.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 theprovidersof 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 ofProvider.loader- The class loader to look providers up with. Must not benull.configuration- AnswersconfigurationKey(),disabledKey()andallowedKey()with the configured value ornull. Must not benull, and must be thread-safe, cheap and free of side effects, as it is called on every resolution.- Returns:
- The providers of
spi. Nevernull. - Throws:
IllegalArgumentException- Thrown if an argument isnull, or ifspiis not a sub-interface ofProvider.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 theprovidersof 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 ofProvider.loader- The class loader to look providers up with. Must not benull.trusted- Accepts the provider classes that may be used. Must not benull.- Returns:
- The providers of
spi. Nevernull. - Throws:
IllegalArgumentException- Thrown if an argument isnull, or ifspiis not a sub-interface ofProvider.ProviderResolutionException- Thrown if the configuration or the service files cannot be read, or iftrustedthrows.
-
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 ofProvider.loader- The class loader to look providers up with. Must not benull.configuration- Answers the configuration keys. Must not benull.trusted- Accepts the provider classes that may be used. Must not benull.- Returns:
- The providers of
spi. Nevernull. - Throws:
IllegalArgumentException- Thrown if an argument isnull, or ifspiis not a sub-interface ofProvider.ProviderResolutionException- Thrown if the service files cannot be read, or iftrustedthrows.
-
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. Nevernull.
-
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 byinstalled(). 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. Nevernull.
-
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. UseofTrusted(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. Nevernull.
-
installed
-
byName
Resolves an availableproviderby name, unless the name is disabled. If several available providers have the name, the one with the highest priority is returned. The key fromconfigurationKey()is not applied.- Parameters:
name- The case-sensitive provider name. Must not benullor blank.- Returns:
- The provider, or
Optional.empty()if the name is disabled or no available provider has it. - Throws:
IllegalArgumentException- Thrown ifnameisnullor blank.AmbiguousProviderException- Thrown if several providers of that name have the highest priority.
-
supporting
Lists the availableprovidersthat support aspec, without the disabled ones. The key fromconfigurationKey()is not applied.- Parameters:
spec- The spec. Must not benull.- Returns:
- The providers ordered by descending priority, providers of equal priority in lookup
order. Unmodifiable and never
null. - Throws:
IllegalArgumentException- Thrown ifspecisnull.
-
select
Resolves theproviderfor aspec. The candidates are the available providers that supportspecand are not disabled. If the key fromconfigurationKey()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 benull.- Returns:
- The provider. Never
null. - Throws:
IllegalArgumentException- Thrown ifspecisnull.UnsatisfiedProviderException- Thrown if no candidate remains.AmbiguousProviderException- Thrown if several candidates have the highest priority.
-