ServiceLoader: services, providers and plug-ins

A service in Java is an interface, or an abstract class, that a program needs, and a service provider is an implementation of it that the program never names in its code. java.util.ServiceLoader finds the providers at run time. A module that looks providers up declares uses com.example.Service;, and each plug-in module declares provides com.example.Service with com.example.impl.Impl;. On the class path, a plug-in JAR lists its provider classes in a text file instead, META-INF/services/com.example.Service. ServiceLoader creates providers lazily, only when you ask for them, so a program can look at what is available first. This is how a host gains features without changing its own code: put another plug-in on the module path, and the next run finds it. The JDK works this way too; DriverManager, for one, finds JDBC drivers as providers of java.sql.Driver.

This lesson builds a shop checkout that finds its payment methods as plug-ins, on Eclipse Temurin 25.0.4.1.

A service and two providers

Four modules take part. kirana.pay exports the service, the interface PaymentMethod. Two plug-ins, kirana.upi and kirana.card, each provide it. kirana.checkout uses it, and requires only kirana.pay:

package com.example.kirana.pay;

/** A way to pay a bill. Plug-ins implement it, and the checkout finds them at run time. */
public interface PaymentMethod {
    /** A short name the checkout shows, such as "UPI". */
    String name();

    /** What the customer is told to do for an amount in paise. */
    String instructions(long paise);

    /** Formats paise as rupees, such as 1418.50; enough for these plug-ins' messages. */
    static String rupees(long paise) {
        return paise / 100 + "." + String.format("%02d", paise % 100);
    }
}

/** A payment plug-in. It provides the service; nothing needs to know its class name. */
module kirana.upi {
    requires kirana.pay;
    provides com.example.kirana.pay.PaymentMethod with com.example.kirana.upi.Upi;
}

package com.example.kirana.upi;

import com.example.kirana.pay.Named;
import com.example.kirana.pay.PaymentMethod;

@Named("UPI")
public class Upi implements PaymentMethod {
    public Upi() {
        System.out.println("  (the UPI plug-in is created)");
    }

    @Override
    public String name() {
        return "UPI";
    }

    @Override
    public String instructions(long paise) {
        return "scan the shop's QR code and approve ₹" + PaymentMethod.rupees(paise) + " in your UPI app";
    }
}

/** The shop's checkout: it uses the payment service and names no plug-in. */
module kirana.checkout {
    requires kirana.pay;
    uses com.example.kirana.pay.PaymentMethod;
}

package com.example.kirana.checkout;

import com.example.kirana.pay.PaymentMethod;
import java.util.Comparator;
import java.util.List;
import java.util.ServiceLoader;

/** Lists every way to pay that a plug-in on the module path offers. */
public class Checkout {
    public static void main(String[] args) {
        long paise = 1_418_50;
        System.out.println("Looking for plug-ins");
        List<PaymentMethod> methods = ServiceLoader.load(PaymentMethod.class).stream()
                .sorted(Comparator.comparing(provider -> provider.type().getName())) // the order found is not defined
                .map(ServiceLoader.Provider::get)
                .toList();
        System.out.println("Bill of ₹" + PaymentMethod.rupees(paise) + ", " + methods.size()
                + (methods.size() == 1 ? " way" : " ways") + " to pay:");
        for (PaymentMethod method : methods) {
            System.out.println("  " + method.name() + ": " + method.instructions(paise));
        }
    }
}

Each part of the arrangement has one job. The service module exports nothing but the interface and what it needs. A plug-in requires the service module, declares provides … with … and exports nothing, as the ServiceLoader documentation recommends, so no code can depend on its classes. The checkout declares uses and calls ServiceLoader.load(PaymentMethod.class); it never requires a plug-in module, so plug-ins can come and go.

The interface lives in a module of its own for a reason. The checkout and every plug-in depend on it, and on nothing of each other, so the dependencies all point one way: a plug-in can be written, compiled and shipped by another team with only the service module in hand, and the checkout can be released without knowing which plug-ins exist.

Loading the providers at run time

from session import run

# The service, two plug-ins and the checkout, each compiled on its own and packed as a modular JAR; the checkout runs
# with both plug-ins on the module path, then with one of them, unchanged.
run(
    """
javac -d out/kirana.pay $(find pay/src -name "*.java")
javac -d out/kirana.upi --module-path out $(find upi/src -name "*.java")
javac -d out/kirana.card --module-path out $(find card/src -name "*.java")
javac -d out/kirana.checkout --module-path out $(find checkout/src -name "*.java")
for m in pay upi card checkout; do jar --create --file mods/kirana.$m.jar -C out/kirana.$m . || exit 1; done
jar --describe-module --file mods/kirana.upi.jar
java --module-path mods --module kirana.checkout/com.example.kirana.checkout.Checkout
java --module-path mods/kirana.pay.jar:mods/kirana.upi.jar:mods/kirana.checkout.jar --module kirana.checkout/com.example.kirana.checkout.Checkout
"""
)

# openjdk version "25.0.4.1" LTS
$ javac -d out/kirana.pay $(find pay/src -name "*.java")
$ javac -d out/kirana.upi --module-path out $(find upi/src -name "*.java")
$ javac -d out/kirana.card --module-path out $(find card/src -name "*.java")
$ javac -d out/kirana.checkout --module-path out $(find checkout/src -name "*.java")
$ for m in pay upi card checkout; do jar --create --file mods/kirana.$m.jar -C out/kirana.$m . || exit 1; done
$ jar --describe-module --file mods/kirana.upi.jar
kirana.upi jar:mods/kirana.upi.jar!/module-info.class
requires java.base mandated
requires kirana.pay
provides com.example.kirana.pay.PaymentMethod with com.example.kirana.upi.Upi
contains com.example.kirana.upi

$ java --module-path mods --module kirana.checkout/com.example.kirana.checkout.Checkout
Looking for plug-ins
  (the Card plug-in is created)
  (the UPI plug-in is created)
Bill of ₹1418.50, 2 ways to pay:
  Card: tap or insert the card; the terminal charges ₹1418.50
  UPI: scan the shop's QR code and approve ₹1418.50 in your UPI app
$ java --module-path mods/kirana.pay.jar:mods/kirana.upi.jar:mods/kirana.checkout.jar --module kirana.checkout/com.example.kirana.checkout.Checkout
Looking for plug-ins
  (the UPI plug-in is created)
Bill of ₹1418.50, 1 way to pay:
  UPI: scan the shop's QR code and approve ₹1418.50 in your UPI app

• The descriptor records the provider. jar --describe-module shows provides com.example.kirana.pay.PaymentMethod with com.example.kirana.upi.Upi in the plug-in’s JAR, which is where ServiceLoader reads it.
• Providers are created on request. Each plug-in prints a line from its constructor, and the lines appear only after “Looking for plug-ins”, when Provider.get() runs.
• The order is chosen, not found. The ServiceLoader documentation says that the order of modules in a layer is not defined, so the checkout sorts the providers by class name before it creates them, and every run lists them the same way.
• Removing a plug-in is a deployment change. The second run left the card plug-in’s JAR off the module path: one way to pay, with nothing recompiled and nothing edited.

The same ServiceLoader.load call also finds plug-ins that are plain JARs on the class path, through their provider files under META-INF/services. A host therefore keeps working when some of its plug-ins are modules and others are not yet, which helps while a plug-in system moves to modules one JAR at a time.

The ServiceLoader API in one table

Check yourself

When plug-ins are created, and how to pick one without creating the others Pro: opens with a Pro, Premium or Ultimate pass

Plug-ins on the class path, and every ServiceConfigurationError case reproduced Pro: opens with a Pro, Premium or Ultimate pass

Exercise: a net-banking plug-in, and a service that can change without breaking plug-ins Pro: opens with a Pro, Premium or Ultimate pass

Key takeaways

• A service is an interface; providers implement it; ServiceLoader finds them at run time.
• Modules declare uses on the host and provides … with … on each plug-in; the host never requires a plug-in.
• On the class path, META-INF/services/<service name> lists the provider classes.
• Providers are created lazily: stream() with Provider.type() lets you choose before anything is created.
• The order in which providers are found is not defined, so sort them or choose by name.