Understanding Java SPI: Principles, Implementation, and Applications

Java SPI (Service Provider Interface) is a mechanism for dynamically loading services. Its core idea is decoupling, which follows a typical micro‑kernel architecture. SPI is extensively used in the Java ecosystem, for example in Dubbo, Spring Boot, and many other frameworks.

Four essential elements of Java SPI :

SPI interface : the contract that service providers must implement.

SPI implementation class : the concrete class that provides the service.

SPI configuration file : a file placed under META-INF/services whose name matches the fully‑qualified name of the SPI interface and whose each line lists a fully‑qualified implementation class name.

ServiceLoader : the core Java class that loads SPI implementations at runtime.

Simple SPI example

Define an SPI interface:

package io.github.dunwu.javacore.spi;

public interface DataStorage {
    String search(String key);
}

Two implementations – MySQL and Redis – are provided:

package io.github.dunwu.javacore.spi;

public class MysqlStorage implements DataStorage {
    @Override
    public String search(String key) {
        return "【Mysql】搜索" + key + "，结果：No";
    }
}

package io.github.dunwu.javacore.spi;

public class RedisStorage implements DataStorage {
    @Override
    public String search(String key) {
        return "【Redis】搜索" + key + "，结果：Yes";
    }
}

The configuration file io.github.dunwu.javacore.spi.DataStorage placed in META-INF/services contains:

io.github.dunwu.javacore.spi.MysqlStorage
io.github.dunwu.javacore.spi.RedisStorage

Loading the services with ServiceLoader :

import java.util.ServiceLoader;

public class SpiDemo {
    public static void main(String[] args) {
        ServiceLoader
serviceLoader = ServiceLoader.load(DataStorage.class);
        System.out.println("============ Java SPI 测试============");
        serviceLoader.forEach(loader -> System.out.println(loader.search("Yes Or No")));
    }
}

Output:

============ Java SPI 测试============
【Mysql】搜索Yes Or No，结果：No
【Redis】搜索Yes Or No，结果：Yes

How ServiceLoader works

The class maintains several member variables, such as the prefix for configuration files ( "META-INF/services/" ), the target service interface, the class loader, a cache of already loaded providers, and a lazy iterator for on‑demand loading.

public final class ServiceLoader
implements Iterable
{
    private static final String PREFIX = "META-INF/services/";
    private final Class
service;
    private final ClassLoader loader;
    private final AccessControlContext acc;
    private LinkedHashMap
providers = new LinkedHashMap<>();
    private LazyIterator lookupIterator;
    // ...
}

The static load method creates a new ServiceLoader instance, which in turn calls reload() to clear the cache and create a lazy iterator. When iterator() is invoked, the loader first returns cached providers; if none exist, it delegates to the lazy iterator.

public Iterator
iterator() {
    return new Iterator
() {
        Iterator
> knownProviders = providers.entrySet().iterator();
        public boolean hasNext() {
            if (knownProviders.hasNext()) return true;
            return lookupIterator.hasNext();
        }
        public S next() {
            if (knownProviders.hasNext()) return knownProviders.next().getValue();
            return lookupIterator.next();
        }
        public void remove() { throw new UnsupportedOperationException(); }
    };
}

The lazy iterator reads the configuration file, parses each line to obtain the implementation class name, loads the class via the specified ClassLoader , and instantiates it with newInstance() . The instance is then cached in providers .

private boolean hasNextService() {
    if (nextName != null) return true;
    if (configs == null) {
        try {
            String fullName = PREFIX + service.getName();
            configs = (loader == null) ? ClassLoader.getSystemResources(fullName) : loader.getResources(fullName);
        } catch (IOException x) { fail(service, "Error locating configuration files", x); }
    }
    while ((pending == null) || !pending.hasNext()) {
        if (!configs.hasMoreElements()) return false;
        pending = parse(service, configs.nextElement());
    }
    nextName = pending.next();
    return true;
}

private S nextService() {
    if (!hasNextService()) throw new NoSuchElementException();
    String cn = nextName; nextName = null;
    try { Class
c = Class.forName(cn, false, loader); }
    catch (ClassNotFoundException x) { fail(service, "Provider " + cn + " not found"); }
    // type check omitted for brevity
    try {
        S p = service.cast(c.newInstance());
        providers.put(cn, p);
        return p;
    } catch (Throwable x) { fail(service, "Provider " + cn + " could not be instantiated", x); }
    throw new Error();
}

Interaction with class loaders

SPI relies on the context class loader to locate configuration files. Because the SPI interface itself is loaded by the bootstrap class loader while implementations are usually loaded by the application class loader, specifying the correct class loader is essential. The typical way to obtain it is:

ClassLoader cl = Thread.currentThread().getContextClassLoader();

Limitations of Java SPI

All implementations are loaded eagerly; there is no on‑demand filtering.

Only an Iterator is provided, making it hard to select a specific implementation based on parameters.

Instances of ServiceLoader are not thread‑safe for concurrent use.

Typical application scenarios

1. JDBC DriverManager : Since JDBC 4.0, drivers are discovered via SPI. The java.sql.Driver interface is the SPI contract, and driver JARs contain a file META-INF/services/java.sql.Driver listing the driver class (e.g., com.mysql.cj.jdbc.Driver ).

Class.forName("com.mysql.cj.jdbc.Driver"); // pre‑JDBC4.0
// After JDBC4.0 the driver is loaded automatically via ServiceLoader

2. Apache Commons Logging : The LogFactory uses SPI to locate a concrete logging implementation. It first checks a system property, then looks for a resource file META-INF/services/org.apache.commons.logging.LogFactory , and finally falls back to a default implementation.

ServiceLoader
loadedDrivers = ServiceLoader.load(Driver.class);
Iterator
it = loadedDrivers.iterator();
while (it.hasNext()) { it.next(); }

3. Spring Boot auto‑configuration : Spring Boot treats many of its starter modules as SPI extensions. The spring.factories file under META-INF/ registers auto‑configuration classes. At startup, SpringFactoriesLoader.loadFactoryNames reads all spring.factories resources, builds a map of factory type to implementation class names, and then instantiates the appropriate configuration classes.

public static List
loadFactoryNames(Class
factoryType, @Nullable ClassLoader classLoader) {
    String factoryTypeName = factoryType.getName();
    return loadSpringFactories(classLoader).getOrDefault(factoryTypeName, Collections.emptyList());
}

4. Dubbo SPI : Dubbo implements its own SPI mechanism. Configuration files are placed under META-INF/dubbo and use a key = class format, allowing named look‑ups, lazy loading, and additional features such as AOP and IoC.

public T getExtension(String name) {
    if (name == null || name.length() == 0) throw new IllegalArgumentException("Extension name == null");
    Holder
holder = cachedInstances.get(name);
    if (holder == null) {
        cachedInstances.putIfAbsent(name, new Holder<>());
        holder = cachedInstances.get(name);
    }
    Object instance = holder.get();
    if (instance == null) {
        synchronized (holder) {
            instance = holder.get();
            if (instance == null) {
                instance = createExtension(name);
                holder.set(instance);
            }
        }
    }
    return (T) instance;
}

Dubbo’s ExtensionLoader follows a similar cache‑first, double‑checked locking pattern, then loads classes from configuration files located in several directories ( META-INF/dubbo/ , META-INF/services/ , etc.).

Overall, Java SPI provides a lightweight, standard way to achieve plug‑in extensibility. Understanding its internals—especially the role of ServiceLoader , class loaders, and configuration files—helps developers diagnose loading issues and design custom extension mechanisms such as those used by Dubbo.