ServiceLoader

the picture

you know how adding the postgres driver jar to your classpath makes DriverManager.getConnection("jdbc:postgresql://…") just work, even though nothing in your code mentions postgres? the driver jar registered itself.

think of a wall socket. the appliance (your code) is built against the socket's shape (an interface). whoever plugs in at the other end (a provider jar) supplies the power. the appliance never needs to know which power company it is, and you can switch companies by swapping a jar.

the three roles:

service

an interface (or abstract class) everyone agrees on. java.sql.Driver, javax.annotation.processing.Processor, your own com.shop.spi.Greeter.

provider

a class implementing it, in some jar, plus a declaration saying so.

consumer

the code that calls ServiceLoader.load(Greeter.class) and iterates whatever turns up.

the smallest real one

the JDK uses it on itself. every command-line tool that can also run in-process registers as a java.util.spi.ToolProvider:

import java.util.ServiceLoader;
import java.util.spi.ToolProvider;
 
void main() {
    var names = ServiceLoader.load(ToolProvider.class).stream()
        .map(provider -> provider.get().name())
        .sorted()
        .toList();
    IO.println(names);
 
    ToolProvider javac = ToolProvider.findFirst("javac").orElseThrow();
    IO.println(javac.getClass().getName());
}

[jar, javac, javadoc, javap, jdeps, jlink, jmod, jnativescan, jpackage]
com.sun.tools.javac.main.JavacToolProvider

nine tools, found at runtime, none of them named in your code. JavacToolProvider lives in the jdk.compiler module, in a package that module doesn't export: you couldn't write new JavacToolProvider() if you tried. you can still get one, because the module provides it.

a plugin, for real

an interface in one jar, two implementations in two more, and an app that only knows the interface:

package com.shop.spi;
 
public interface Greeter {
    String lang();
    String greet(String name);
}

package com.shop.fr;
 
import com.shop.spi.Greeter;
 
public class French implements Greeter {
    public French() { System.out.println("  (French constructed)"); }
    public String lang() { return "fr"; }
    public String greet(String name) { return "bonjour, " + name; }
}

com.shop.fr.French

import com.shop.spi.Greeter;
import java.util.ServiceLoader;
 
public class Main {
    public static void main(String[] args) {
        for (Greeter g : ServiceLoader.load(Greeter.class)) {
            System.out.println(g.lang() + ": " + g.greet("ada"));
        }
    }
}

greeter-en.jar is the same with English. inside the provider jar, the registration is one small text file:

build them and change nothing but the class path:

$ java -cp shop-api.jar:app.jar Main
$ java -cp shop-api.jar:app.jar:greeter-en.jar Main
en: hello, ada
$ java -cp shop-api.jar:app.jar:greeter-en.jar:greeter-fr.jar Main
en: hello, ada
  (French constructed)
fr: bonjour, ada
$ java -cp shop-api.jar:app.jar:greeter-fr.jar:greeter-en.jar Main
  (French constructed)
fr: bonjour, ada
en: hello, ada

same app.jar, three behaviours. and look at where (French constructed) lands: after the English greeting, not at the start. the loader reads the service files up front but only instantiates each provider when the iterator reaches it.

$ java -cp …
en: hello, ada
  (French constructed)
fr: bonjour, ada

the module way

on the module path, the text file is replaced by declarations the JVM checks when it resolves the module graph:

module shop.fr {
    requires shop.api;
    provides com.shop.spi.Greeter with com.shop.fr.French;
}

module shop.app {
    requires shop.api;
    uses com.shop.spi.Greeter;
}

three things change:

• the provider's package can stay private. shop.fr exports nothing. nobody can new French(), but ServiceLoader can still hand one out.
• a provider can be a factory. if the class has a public static Greeter provider() method, that's called instead of a constructor, so the provider can return a singleton or a cached instance.
• uses is mandatory. leave it out and using the loader throws (real message below). it's the module system's way of making service dependencies visible in the descriptor, where jlink can read them (jlink --bind-services pulls in every module that provides a service you use, see jlink).

Exception in thread "main" java.util.ServiceConfigurationError: com.shop.spi.Greeter: module shop.app does not declare `uses`

old-style jars on the class path still work when the app itself is a module: i put greeter-en.jar on the class path next to a modular shop.app, and the loader found it through its META-INF/services file. migrating is one side at a time (class path to module path).

where it's already working for you

compared to a DI container, it's tiny: no injection, no scopes, no configuration. just "give me every implementation of this interface that's on the path". that's often all a plugin system needs.