Package 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 Details

    • 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 instance.

    • 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.