java.util

Class ServiceLoader<S>

java.lang.Object

java.util.ServiceLoader<S>

Type Parameters:

S - the service class or interface

All Implemented Interfaces:

Iterable<S>

public final class ServiceLoader<S>
extends Object
implements Iterable<S>

A service-provider loader.

A service provider is a factory for creating all known implementations of a particular class or interface S. The known implementations are read from a configuration file in META-INF/services/. The file's name should match the class' binary name (such as java.util.Outer$Inner).

The file format is as follows. The file's character encoding must be UTF-8. Whitespace is ignored, and # is used to begin a comment that continues to the next newline. Lines that are empty after comment removal and whitespace trimming are ignored. Otherwise, each line contains the binary name of one implementation class. Duplicate entries are ignored, but entries are otherwise returned in order (that is, the file is treated as an ordered set).

Given these classes:

 package a.b.c;
 public interface MyService { ... }
 public class MyImpl1 implements MyService { ... }
 public class MyImpl2 implements MyService { ... }
 

And this configuration file (stored as META-INF/services/a.b.c.MyService):

 # Known MyService providers.
 a.b.c.MyImpl1  # The original implementation for handling "bar"s.
 a.b.c.MyImpl2  # A later implementation for "foo"s.
 

You might use ServiceProvider something like this:

   for (MyService service : ServiceLoader.load(MyService.class)) {
     if (service.supports(o)) {
       return service.handle(o);
     }
   }
 

Note that each iteration creates new instances of the various service implementations, so any heavily-used code will likely want to cache the known implementations itself and reuse them. Note also that the candidate classes are instantiated lazily as you call next on the iterator: construction of the iterator itself does not instantiate any of the providers.

Since:

1.6

Method Summary

Modifier and Type	Method and Description
Iterator<S>	iterator() Returns an iterator over all the service providers offered by this service loader.
static <S> ServiceLoader<S>	load(Class<S> service) Constructs a service loader, using the current thread's context class loader.
static <S> ServiceLoader<S>	load(Class<S> service, ClassLoader classLoader) Constructs a service loader.
static <S> S	loadFromSystemProperty(Class<S> service) Internal API to support built-in SPIs that check a system property first.
static <S> ServiceLoader<S>	loadInstalled(Class<S> service) Constructs a service loader, using the extension class loader.
void	reload() Invalidates the cache of known service provider class names.
String	toString() Returns a string containing a concise, human-readable description of this object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

reload

public void reload()

Invalidates the cache of known service provider class names.

iterator

public Iterator<S> iterator()

Returns an iterator over all the service providers offered by this service loader. Note that hasNext and next may throw if the configuration is invalid.

Each iterator will return new instances of the classes it iterates over, so callers may want to cache the results of a single call to this method rather than call it repeatedly.

The returned iterator does not support remove.

Specified by:

iterator in interface Iterable<S>

Returns:

an Iterator.

load

public static <S> ServiceLoader<S> load(Class<S> service,
                                        ClassLoader classLoader)

Constructs a service loader. If classLoader is null, the system class loader is used.

Parameters:

service - the service class or interface

classLoader - the class loader

Returns:

a new ServiceLoader

load

public static <S> ServiceLoader<S> load(Class<S> service)

Constructs a service loader, using the current thread's context class loader.

Parameters:

service - the service class or interface

Returns:

a new ServiceLoader

loadInstalled

public static <S> ServiceLoader<S> loadInstalled(Class<S> service)

Constructs a service loader, using the extension class loader.

Parameters:

service - the service class or interface

Returns:

a new ServiceLoader

loadFromSystemProperty

public static <S> S loadFromSystemProperty(Class<S> service)

Internal API to support built-in SPIs that check a system property first. Returns an instance specified by a property with the class' binary name, or null if no such property is set.

toString

public String toString()

Description copied from class: Object

Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression:

   getClass().getName() + '@' + Integer.toHexString(hashCode())

See Writing a useful toString method if you intend implementing your own toString method.

Overrides:

toString in class Object

Returns:

a printable representation of this object.