to top
Android APIs
public final class

ServiceLoader

extends Object
implements Iterable<T>
java.lang.Object
   ↳ java.util.ServiceLoader<S>

Class Overview

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.

Summary

Public Methods
Iterator<S> iterator()
Returns an iterator over all the service providers offered by this service loader.
static <S> ServiceLoader<S> load(Class<S> service, ClassLoader classLoader)
Constructs a 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> 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.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.lang.Iterable

Public Methods

public Iterator<S> iterator ()

Since: API Level 9

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.

Returns
  • An Iterator instance.

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

Since: API Level 9

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

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

Since: API Level 9

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

Parameters
service the service class or interface
Returns
  • a new ServiceLoader

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

Since: API Level 9

Constructs a service loader, using the extension class loader.

Parameters
service the service class or interface
Returns
  • a new ServiceLoader

public void reload ()

Since: API Level 9

Invalidates the cache of known service provider class names.

public String toString ()

Since: API Level 9

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.

Returns
  • a printable representation of this object.