- Type Parameters:
T
- The type of the service to be loaded by this finder
- All Implemented Interfaces:
Iterable<T>
In this lookup mechanism a service is represented by an interface or an
abstract class. (A concrete class may be used, but this is not
recommended.) A provider of a given service contains one or more concrete
classes that extend this service class with data and code specific to
the provider. This provider class will typically not be the entire
provider itself but rather a proxy that contains enough information to
decide whether the provider is able to satisfy a particular request together
with code that can create the actual provider on demand. The details of
provider classes tend to be highly service-specific; no single class or
interface could possibly unify them, so no such class has been defined. The
only requirement enforced here is that provider classes must have a
zero-argument constructor so that they may be instantiated during lookup.
A service provider identifies itself by placing a provider-configuration
file in the resource directory META-INF/services
. The file's name
should consist of the fully-qualified name of the abstract service class.
The file should contain a list of fully-qualified concrete provider-class
names, one per line. Space and tab characters surrounding each name, as
well as blank lines, are ignored. The comment character is '#'
(0x23
); on each line all characters following the first comment
character are ignored. The file must be encoded in UTF-8.
If a particular concrete provider class is named in more than one
configuration file, or is named in the same configuration file more than
once, then the duplicates will be ignored. The configuration file naming a
particular provider need not be in the same jar file or other distribution
unit as the provider itself. The provider must be accessible from the same
class loader that was initially queried to locate the configuration file;
note that this is not necessarily the class loader that found the file.
Example: Suppose we have a service class named
java.io.spi.CharCodec
. It has two abstract methods:
public abstract CharEncoder getEncoder(String encodingName); public abstract CharDecoder getDecoder(String encodingName);
Each method returns an appropriate object or
null
if it cannot
translate the given encoding. Typical CharCodec
providers will
support more than one encoding.
If sun.io.StandardCodec
is a provider of the CharCodec
service then its jar file would contain the file
META-INF/services/java.io.spi.CharCodec
. This file would contain
the single line:
sun.io.StandardCodec # Standard codecs for the platform
To locate an codec for a given encoding name, the internal I/O code would do something like this:
CharEncoder getEncoder(String encodingName) { for( CharCodec cc : ServiceFinder.find(CharCodec.class) ) { CharEncoder ce = cc.getEncoder(encodingName); if (ce != null) return ce; } return null; }
The provider-lookup mechanism always executes in the security context of the caller. Trusted system code should typically invoke the methods in this class from within a privileged security context.
- Since:
- 1.3
- Version:
- 1.11, 03/12/19
- Author:
- Mark Reinhold
-
Method Summary
Modifier and TypeMethodDescriptionstatic <T> ServiceFinder<T>
Locates and incrementally instantiates the available providers of a given service using the context class loader.static <T> ServiceFinder<T>
static <T> ServiceFinder<T>
find
(Class<T> service, Component component, ServiceLoader<T> serviceLoader) static <T> ServiceFinder<T>
find
(Class<T> service, ClassLoader loader) Locates and incrementally instantiates the available providers of a given service using the given class loader.static <T> ServiceFinder<T>
find
(Class<T> service, ClassLoader loader, Component component) static <T> ServiceFinder<T>
find
(Class<T> service, ServiceLoader<T> serviceLoader) iterator()
Returns discovered objects incrementally.T[]
toArray()
Returns discovered objects all at once.Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.lang.Iterable
forEach, spliterator
-
Method Details
-
find
public static <T> ServiceFinder<T> find(@NotNull Class<T> service, @Nullable ClassLoader loader, Component component) -
find
public static <T> ServiceFinder<T> find(@NotNull Class<T> service, Component component, @NotNull ServiceLoader<T> serviceLoader) -
find
-
find
Locates and incrementally instantiates the available providers of a given service using the given class loader.
This method transforms the name of the given service class into a provider-configuration filename as described above and then uses the
getResources
method of the given class loader to find all available files with that name. These files are then read and parsed to produce a list of provider-class names. The iterator that is returned uses the given class loader to lookup and then instantiate each element of the list.
Because it is possible for extensions to be installed into a running Java virtual machine, this method may return different results each time it is invoked.
- Type Parameters:
T
- The type of the service to be loaded by this finder- Parameters:
service
- The service's abstract service classloader
- The class loader to be used to load provider-configuration files and instantiate provider classes, ornull
if the system class loader (or, failing that the bootstrap class loader) is to be used- Returns:
- A new service finder
- Throws:
ServiceConfigurationError
- If a provider-configuration file violates the specified format or names a provider class that cannot be found and instantiated- See Also:
-
find
Locates and incrementally instantiates the available providers of a given service using the context class loader. This convenience method is equivalent to
ClassLoader cl = Thread.currentThread().getContextClassLoader(); return Service.providers(service, cl);
- Type Parameters:
T
- The type of the service to be loaded by this finder- Parameters:
service
- The service's abstract service class- Returns:
- A new service finder
- Throws:
ServiceConfigurationError
- If a provider-configuration file violates the specified format or names a provider class that cannot be found and instantiated- See Also:
-
find
public static <T> ServiceFinder<T> find(@NotNull Class<T> service, @NotNull ServiceLoader<T> serviceLoader) -
iterator
Returns discovered objects incrementally.- Specified by:
iterator
in interfaceIterable<T>
- Returns:
- An
Iterator
that yields provider objects for the given service, in some arbitrary order. The iterator will throw aServiceConfigurationError
if a provider-configuration file violates the specified format or if a provider class cannot be found and instantiated.
-
toArray
Returns discovered objects all at once.- Returns:
- can be empty but never null.
-