public final class Service extends Object
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 platformTo locate an encoder for a given encoding name, the internal I/O code would do something like this:
CharEncoder getEncoder(String encodingName) {
Iterator ps = Service.providers(CharCodec.class);
while (ps.hasNext()) {
CharCodec cc = (CharCodec)ps.next();
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.| Modifier and Type | Method and Description |
|---|---|
static Iterator |
installedProviders(Class service)
Locates and incrementally instantiates the available providers of a
given service using the extension class loader.
|
static Iterator |
providers(Class service)
Locates and incrementally instantiates the available providers of a
given service using the context class loader.
|
static Iterator |
providers(Class service,
ClassLoader loader)
Locates and incrementally instantiates the available providers of a
given service using the given class loader.
|
public static Iterator providers(Class service, ClassLoader loader) throws ServiceConfigurationError
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.
service - The service's abstract service classloader - The class loader to be used to load provider-configuration files
and instantiate provider classes, or null if the system
class loader (or, failing that the bootstrap class loader) is to
be usedServiceConfigurationError - If a provider-configuration file violates the specified format
or names a provider class that cannot be found and instantiatedproviders(java.lang.Class),
installedProviders(java.lang.Class)public static Iterator providers(Class service) throws ServiceConfigurationError
ClassLoader cl = Thread.currentThread().getContextClassLoader(); return Service.providers(service, cl);
service - The service's abstract service classServiceConfigurationError - If a provider-configuration file violates the specified format
or names a provider class that cannot be found and instantiatedproviders(java.lang.Class, java.lang.ClassLoader)public static Iterator installedProviders(Class service) throws ServiceConfigurationError
return Service.providers(service, extClassLoader);If the extension class loader cannot be found then the system class loader is used; if there is no system class loader then the bootstrap class loader is used.
service - The service's abstract service classServiceConfigurationError - If a provider-configuration file violates the specified format
or names a provider class that cannot be found and instantiatedproviders(java.lang.Class, java.lang.ClassLoader)