Definition
- Service Provider Interface (SPI) – a pattern separating the service interface, the provider implementation, and the consumer that needs the capability.
META-INF/services– classpath text files listing provider class names; each line is a fully-qualified implementation class.provides ... with– module-system declaration replacing text files; compiler-verified.- Lazy loading – providers are instantiated only as you iterate
ServiceLoader, not all at once. - Context class loader – the default loader for discovery; lets frameworks reach application-level providers that parent delegation would miss.
Imagine National Bank of India wants fee calculators from different vendors without hard-coding any vendor's name. The bank publishes a job description (the interface). Vendors drop a signed card into a well-known mailbox (the META-INF services file) saying "my class fulfills that job." When the bank needs calculators, it opens the mailbox, reads every card, and hires each vendor only when actually needed.
Understanding the Concepts
What is the Service Provider Interface pattern?
The SPI pattern separates three roles:
- Service – an interface or abstract class defining a capability.
- Provider – a concrete implementation, usually in its own jar.
- Consumer – code that needs the capability but should not depend on any specific provider.
ServiceLoader connects consumers to providers without a compile-time dependency. This is how the JDK loads JDBC drivers, charset providers, and logging backends.
package com.bank.spi;
import java.math.BigDecimal;
// The service interface
public interface FeeCalculator {
String name();
BigDecimal calculate(String accountType, BigDecimal amount);
}
How does classpath discovery work?
A provider jar contains a text file at META-INF/services/com.bank.spi.FeeCalculator. Each line is the fully-qualified name of an implementation class.
# META-INF/services/com.bank.spi.FeeCalculator
com.vendor.gst.GstFeeCalculator
com.vendor.flat.FlatFeeCalculator
package com.vendor.gst;
import com.bank.spi.FeeCalculator;
import java.math.BigDecimal;
public class GstFeeCalculator implements FeeCalculator {
@Override
public String name() {
return "GST Fee";
}
@Override
public BigDecimal calculate(String accountType, BigDecimal amount) {
// 18% GST on service fee
BigDecimal serviceFee = amount.multiply(new BigDecimal("0.005"));
return serviceFee.multiply(new BigDecimal("1.18"));
}
}
package com.vendor.flat;
import com.bank.spi.FeeCalculator;
import java.math.BigDecimal;
public class FlatFeeCalculator implements FeeCalculator {
private static final BigDecimal FLAT_FEE = new BigDecimal("50.00");
@Override
public String name() {
return "Flat Fee";
}
@Override
public BigDecimal calculate(String accountType, BigDecimal amount) {
return FLAT_FEE;
}
}
How does the consumer load providers?
The consumer calls ServiceLoader.load(FeeCalculator.class) and iterates. Providers are instantiated lazily as you iterate.
package com.bank.billing;
import com.bank.spi.FeeCalculator;
import java.math.BigDecimal;
import java.util.ServiceLoader;
public class BillingEngine {
public static void main(String[] args) {
BigDecimal transferAmount = new BigDecimal("25000.00");
BigDecimal totalFees = BigDecimal.ZERO;
// Discover and load all fee calculators
ServiceLoader<FeeCalculator> loader =
ServiceLoader.load(FeeCalculator.class);
for (FeeCalculator calc : loader) {
BigDecimal fee = calc.calculate("savings", transferAmount);
System.out.println(calc.name() + ": " + fee);
totalFees = totalFees.add(fee);
}
System.out.println("Total fees: " + totalFees);
}
}
GST Fee: 147.50
Flat Fee: 50.00
Total fees: 197.50
Why is lazy loading important?
The loader does not read all files and instantiate everything up front. As you iterate, it locates the next provider, loads the class, and instantiates it one at a time. This lets you:
- Stop after finding a suitable provider.
- Handle per-provider failures without crashing.
// Using stream() for lazy inspection before instantiation
ServiceLoader.load(FeeCalculator.class).stream()
.filter(p -> p.type().getSimpleName().startsWith("Gst"))
.map(ServiceLoader.Provider::get)
.forEach(calc -> System.out.println(calc.name()));
How does discovery work in the module system?
In modules, the text file is replaced by a declarative provides ... with in module-info.java.
// Provider module
module com.vendor.gst {
requires com.bank.spi;
provides com.bank.spi.FeeCalculator
with com.vendor.gst.GstFeeCalculator;
}
// Consumer module
module com.bank.billing {
requires com.bank.spi;
uses com.bank.spi.FeeCalculator;
}
The compiler verifies these declarations, so a misspelled provider is caught at build time, not runtime.
What role does the context class loader play?
By default, ServiceLoader.load(Service.class) uses the thread's context class loader. This is the back-channel frameworks use so that discovery can reach application-level providers that strict parent delegation would miss.
// Default: uses thread context class loader
ServiceLoader.load(FeeCalculator.class);
// Explicit class loader for precise control
ServiceLoader.load(FeeCalculator.class, myClassLoader);
What are the provider instantiation rules?
On the classpath, providers must have a public no-argument constructor. The modern alternative is a static provider() method that returns an instance.
public class GstFeeCalculator implements FeeCalculator {
// Option 1: public no-arg constructor (default)
public GstFeeCalculator() {}
// Option 2: static provider method
public static FeeCalculator provider() {
return new GstFeeCalculator();
}
// ... implementation
}
What are the error handling considerations?
Iterating can throw ServiceConfigurationError if a declared provider is missing, is not a subtype, or fails to instantiate. Robust consumers iterate defensively.
ServiceLoader<FeeCalculator> loader =
ServiceLoader.load(FeeCalculator.class);
for (var provider : loader) {
try {
BigDecimal fee = provider.calculate("savings", amount);
System.out.println(provider.name() + ": " + fee);
} catch (ServiceConfigurationError e) {
System.err.println("Skipping bad provider: " + e.getMessage());
}
}
What should a senior engineer know?
Service loading is unordered. If you need priority, add your own ranking via an annotation or a method on the interface, and sort the discovered providers yourself. The payoff is genuine extensibility: you add a capability by dropping a jar or module on the path, with zero changes to the consumer code. This is why JDBC drivers, logging frameworks, and many JDK subsystems use SPI.
Visual Overview
ServiceLoader Discovery:
Provider JARs on classpath:
┌─────────────────────────────────────────────┐
│ gst-fee.jar │
│ META-INF/services/com.bank.spi.FeeCalculator │
│ → com.vendor.gst.GstFeeCalculator │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ flat-fee.jar │
│ META-INF/services/com.bank.spi.FeeCalculator │
│ → com.vendor.flat.FlatFeeCalculator │
└─────────────────────────────────────────────┘
Consumer:
ServiceLoader.load(FeeCalculator.class)
│
▼ (lazy iteration)
GstFeeCalculator → instantiated on first next()
FlatFeeCalculator → instantiated on second next()
Key Takeaway
ServiceLoader is Java's built-in SPI mechanism for discovering implementations of an interface at runtime without the consumer naming concrete classes. On the classpath, providers advertise themselves with a text file at META-INF/services/ listing their class names. In the module system, the provides ... with directive in module-info.java replaces the text file and is compiler-verified.
The consumer calls ServiceLoader.load(FeeCalculator.class) and iterates. Loading is lazy: providers are instantiated only as you iterate, which lets you stop early and handle per-provider failures. Discovery uses the thread's context class loader by default, which is the back-channel frameworks use to reach application-level providers.
At National Bank of India, Pankaj built a billing engine that discovered fee calculators from multiple vendors without editing the engine code. A GST calculator and a flat-fee calculator each shipped their own jar with a META-INF/services file. When the engine loaded, ServiceLoader found both, applied each to Rajesh's transfer, and summed the fees. Months later, a new vendor added a calculator just by dropping a jar on the classpath.
The senior points are that service loading is unordered, so add your own ranking if you need priority. Iterating can throw ServiceConfigurationError for broken providers, so iterate defensively. The payoff is genuine extensibility: add a capability by dropping a jar, with zero changes to the consumer.
Remember one sentence: ServiceLoader discovers and lazily loads provider implementations from META-INF/services files or module provides directives, decoupling the consumer from the concrete provider.
---