A service is a well-known set of interfaces and (usually + * abstract) classes. A service provider is a specific implementation + * of a service. The classes in a provider typically implement the interfaces + * and subclass the classes defined in the service itself. Service providers + * can be installed in an implementation of the Java platform in the form of + * extensions, that is, jar files placed into any of the usual extension + * directories. Providers can also be made available by adding them to the + * application's class path or by some other platform-specific means. + * + *
For the purpose of loading, a service is represented by a single type, + * that is, a single interface or abstract class. (A concrete class can be + * used, but this is not recommended.) A provider of a given service contains + * one or more concrete classes that extend this service type with data + * and code specific to the provider. The provider class is typically + * not the entire provider itself but rather a proxy which 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 type is + * defined here. The only requirement enforced by this facility is that + * provider classes must have a zero-argument constructor so that they can be + * instantiated during loading. + * + *
A service provider is identified by placing a + * provider-configuration file in the resource directory + * META-INF/services. The file's name is the fully-qualified binary name of the service's type. + * The file contains a list of fully-qualified binary names of concrete + * provider classes, one per line. Space and tab characters surrounding each + * name, as well as blank lines, are ignored. The comment character is + * '#' ('\u0023', NUMBER SIGN); 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 are 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 from which the file was + * actually loaded. + * + *
Providers are located and instantiated lazily, that is, on demand. A + * service loader maintains a cache of the providers that have been loaded so + * far. Each invocation of the {@link #iterator iterator} method returns an + * iterator that first yields all of the elements of the cache, in + * instantiation order, and then lazily locates and instantiates any remaining + * providers, adding each one to the cache in turn. The cache can be cleared + * via the {@link #reload reload} method. + * + *
Service loaders always execute in the security context of the caller. + * Trusted system code should typically invoke the methods in this class, and + * the methods of the iterators which they return, from within a privileged + * security context. + * + *
Instances of this class are not safe for use by multiple concurrent + * threads. + * + *
Unless otherwise specified, passing a null argument to any + * method in this class will cause a {@link NullPointerException} to be thrown. + * + * + *
Example + * Suppose we have a service type com.example.CodecSet which is + * intended to represent sets of encoder/decoder pairs for some protocol. In + * this case it is an abstract class with two abstract methods: + * + *
+ * + * Each method returns an appropriate object or null if the provider + * does not support the given encoding. Typical providers support more than + * one encoding. + * + *+ * public abstract Encoder getEncoder(String encodingName); + * public abstract Decoder getDecoder(String encodingName);
If com.example.impl.StandardCodecs is an implementation of the + * CodecSet service then its jar file also contains a file named + * + *
+ * + *+ * META-INF/services/com.example.CodecSet
This file contains the single line: + * + *
+ * + *+ * com.example.impl.StandardCodecs # Standard codecs
The CodecSet class creates and saves a single service instance + * at initialization: + * + *
+ * + *+ * private static ServiceLoader<CodecSet> codecSetLoader + * = ServiceLoader.load(CodecSet.class);
To locate an encoder for a given encoding name it defines a static + * factory method which iterates through the known and available providers, + * returning only when it has located a suitable encoder or has run out of + * providers. + * + *
+ * public static Encoder getEncoder(String encodingName) {
+ * for (CodecSet cp : codecSetLoader) {
+ * Encoder enc = cp.getEncoder(encodingName);
+ * if (enc != null)
+ * return enc;
+ * }
+ * return null;
+ * }A getDecoder method is defined similarly. + * + * + *
Usage Note If + * the class path of a class loader that is used for provider loading includes + * remote network URLs then those URLs will be dereferenced in the process of + * searching for provider-configuration files. + * + *
This activity is normal, although it may cause puzzling entries to be + * created in web-server logs. If a web server is not configured correctly, + * however, then this activity may cause the provider-loading algorithm to fail + * spuriously. + * + *
A web server should return an HTTP 404 (Not Found) response when a
+ * requested resource does not exist. Sometimes, however, web servers are
+ * erroneously configured to return an HTTP 200 (OK) response along with a
+ * helpful HTML error page in such cases. This will cause a {@link
+ * ServiceConfigurationError} to be thrown when this class attempts to parse
+ * the HTML page as a provider-configuration file. The best solution to this
+ * problem is to fix the misconfigured web server to return the correct
+ * response code (HTTP 404) along with the HTML error page.
+ *
+ * @param After invoking this method, subsequent invocations of the {@link
+ * #iterator() iterator} method will lazily look up and instantiate
+ * providers from scratch, just as is done by a newly-created loader.
+ *
+ * This method is intended for use in situations in which new providers
+ * can be installed into a running Java virtual machine.
+ */
+ public void reload() {
+ providers.clear();
+ lookupIterator = new LazyIterator(service, loader);
+ }
+
+ private ServiceLoader(Class The iterator returned by this method first yields all of the
+ * elements of the provider cache, in instantiation order. It then lazily
+ * loads and instantiates any remaining providers, adding each one to the
+ * cache in turn.
+ *
+ * To achieve laziness the actual work of parsing the available
+ * provider-configuration files and instantiating providers must be done by
+ * the iterator itself. Its {@link java.util.Iterator#hasNext hasNext} and
+ * {@link java.util.Iterator#next next} methods can therefore throw a
+ * {@link ServiceConfigurationError} if a provider-configuration file
+ * violates the specified format, or if it names a provider class that
+ * cannot be found and instantiated, or if the result of instantiating the
+ * class is not assignable to the service type, or if any other kind of
+ * exception or error is thrown as the next provider is located and
+ * instantiated. To write robust code it is only necessary to catch {@link
+ * ServiceConfigurationError} when using a service iterator.
+ *
+ * If such an error is thrown then subsequent invocations of the
+ * iterator will make a best effort to locate and instantiate the next
+ * available provider, but in general such recovery cannot be guaranteed.
+ *
+ * The iterator returned by this method does not support removal.
+ * Invoking its {@link java.util.Iterator#remove() remove} method will
+ * cause an {@link UnsupportedOperationException} to be thrown.
+ *
+ * @return An iterator that lazily loads providers for this loader's
+ * service
+ */
+ public Iterator An invocation of this convenience method of the form
+ *
+ * This convenience method simply locates the extension class loader,
+ * call it extClassLoader, and then returns
+ *
+ * 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.
+ *
+ * This method is intended for use when only installed providers are
+ * desired. The resulting service will only find and load providers that
+ * have been installed into the current Java virtual machine; providers on
+ * the application's class path will be ignored.
+ *
+ * @param service
+ * The interface or abstract class representing the service
+ *
+ * @return A new service loader
+ */
+ public static
+ * The type of the service to be loaded by this loader
+ *
+ * @author Mark Reinhold
+ * @since 1.6
+ */
+
+public final class ServiceLoader
+ implements Iterable
+{
+
+ private static final String PREFIX = "META-INF/services/";
+
+ // The class or interface representing the service being loaded
+ private Class service;
+
+ // The class loader used to locate, load, and instantiate providers
+ private ClassLoader loader;
+
+ // Cached providers, in instantiation order
+ private LinkedHashMap svc, ClassLoader cl) {
+ service = svc;
+ loader = cl;
+ reload();
+ }
+
+ private static void fail(Class service, String msg, Throwable cause)
+ throws ServiceConfigurationError
+ {
+ throw new ServiceConfigurationError(service.getName() + ": " + msg,
+ cause);
+ }
+
+ private static void fail(Class service, String msg)
+ throws ServiceConfigurationError
+ {
+ throw new ServiceConfigurationError(service.getName() + ": " + msg);
+ }
+
+ private static void fail(Class service, URL u, int line, String msg)
+ throws ServiceConfigurationError
+ {
+ fail(service, u + ":" + line + ": " + msg);
+ }
+
+ // Parse a single line from the given configuration file, adding the name
+ // on the line to the names list.
+ //
+ private int parseLine(Class service, URL u, BufferedReader r, int lc,
+ List
+ {
+
+ Class service;
+ ClassLoader loader;
+ Enumeration service, ClassLoader loader) {
+ this.service = service;
+ this.loader = loader;
+ }
+
+ public boolean hasNext() {
+ if (nextName != null) {
+ return true;
+ }
+ if (configs == null) {
+ try {
+ String fullName = PREFIX + service.getName();
+ if (loader == null)
+ configs = ClassLoader.getSystemResources(fullName);
+ else
+ configs = loader.getResources(fullName);
+ } catch (IOException x) {
+ fail(service, "Error locating configuration files", x);
+ }
+ }
+ while ((pending == null) || !pending.hasNext()) {
+ if (!configs.hasMoreElements()) {
+ return false;
+ }
+ pending = parse(service, configs.nextElement());
+ }
+ nextName = pending.next();
+ return true;
+ }
+
+ public S next() {
+ if (!hasNext()) {
+ throw new NoSuchElementException();
+ }
+ String cn = nextName;
+ nextName = null;
+ try {
+ S p = service.cast(Class.forName(cn, true, loader)
+ .newInstance());
+ providers.put(cn, p);
+ return p;
+ } catch (ClassNotFoundException x) {
+ fail(service,
+ "Provider " + cn + " not found");
+ } catch (Throwable x) {
+ fail(service,
+ "Provider " + cn + " could not be instantiated: " + x,
+ x);
+ }
+ throw new Error(); // This cannot happen
+ }
+
+ public void remove() {
+ throw new UnsupportedOperationException();
+ }
+
+ }
+
+ /**
+ * Lazily loads the available providers of this loader's service.
+ *
+ * Design Note
+ * Throwing an error in these cases may seem extreme. The rationale for
+ * this behavior is that a malformed provider-configuration file, like a
+ * malformed class file, indicates a serious problem with the way the Java
+ * virtual machine is configured or is being used. As such it is
+ * preferable to throw an error rather than try to recover or, even worse,
+ * fail silently.
+ *
+ * iterator() {
+ return new Iterator() {
+
+ Iterator ServiceLoader load(Class service,
+ ClassLoader loader)
+ {
+ return new ServiceLoader(service, loader);
+ }
+
+ /**
+ * Creates a new service loader for the given service type, using the
+ * current thread's {@linkplain java.lang.Thread#getContextClassLoader
+ * context class loader}.
+ *
+ *
+ *
+ * is equivalent to
+ *
+ *
+ * ServiceLoader.load(service)
+ *
+ * @param service
+ * The interface or abstract class representing the service
+ *
+ * @return A new service loader
+ */
+ public static
+ * ServiceLoader.load(service,
+ * Thread.currentThread().getContextClassLoader())
ServiceLoader load(Class service) {
+ ClassLoader cl = Thread.currentThread().getContextClassLoader();
+ return ServiceLoader.load(service, cl);
+ }
+
+ /**
+ * Creates a new service loader for the given service type, using the
+ * extension class loader.
+ *
+ *
+ *
+ *
+ * ServiceLoader.load(service, extClassLoader)
ServiceLoader loadInstalled(Class service) {
+ ClassLoader cl = ClassLoader.getSystemClassLoader();
+ ClassLoader prev = null;
+ while (cl != null) {
+ prev = cl;
+ cl = cl.getParent();
+ }
+ return ServiceLoader.load(service, prev);
+ }
+
+ /**
+ * Returns a string describing this service.
+ *
+ * @return A descriptive string
+ */
+ public String toString() {
+ return "java.util.ServiceLoader[" + service.getName() + "]";
+ }
+
+}