java.lang.Object

cloud.opencode.base.core.spi.SpiLoader

public final class SpiLoader extends Object

SPI Loader - Service Provider Interface loading utility SPI 加载器 - 服务提供者接口加载工具

Provides cached SPI service loading using Java ServiceLoader mechanism.

使用 Java ServiceLoader 机制提供带缓存的 SPI 服务加载。

Features | 主要功能:

Load all implementations (load) - 加载所有实现
Load first implementation (loadFirst) - 加载第一个实现
Load with default (loadFirstOrDefault) - 带默认值加载
Filter by type (loadByType) - 按类型过滤
Cached loading for performance - 缓存加载提升性能
Reload support (reload) - 重新加载支持
Safe loading with error isolation (loadSafe) - 带错误隔离的安全加载
Priority-ordered loading (loadOrdered) - 按优先级排序加载

Usage Examples | 使用示例:

List<MyService> services = SpiLoader.load(MyService.class);
Optional<MyService> first = SpiLoader.loadFirst(MyService.class);
MyService service = SpiLoader.loadFirstOrDefault(MyService.class, defaultImpl);

if (SpiLoader.hasService(MyService.class)) {
    int count = SpiLoader.count(MyService.class);
}

// Error-isolated loading | 带错误隔离的加载
List<MyService> safe = SpiLoader.loadSafe(MyService.class);  // skips broken providers

// Priority-ordered loading | 按优先级排序加载
List<MyService> ordered = SpiLoader.loadOrdered(MyService.class);

Security | 安全性:

Thread-safe: Yes (ConcurrentHashMap) - 线程安全: 是
Null-safe: Yes - 空值安全: 是

Since:

JDK 25, opencode-base-core V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

static void

clearCache()

Clears the cache 清除缓存

static void

clearCache(Class<?> serviceClass)

Clears the cache for the specified class 清除指定类的缓存

static <T> int

count(Class<T> serviceClass)

Gets the SPI service count 获取 SPI 服务数量

static <T> boolean

hasService(Class<T> serviceClass)

Checks if the SPI service exists 检查 SPI 服务是否存在

static <T> List<T>

load(Class<T> serviceClass)

Loads SPI service implementations 加载 SPI 服务实现

static <T> List<T>

load(Class<T> serviceClass, ClassLoader classLoader)

Loads SPI service implementations (with specified ClassLoader) 加载 SPI 服务实现（指定类加载器）

static <T, S extends T> List<S>

loadByType(Class<T> serviceClass, Class<S> targetType)

Filters SPI services by type 按类型过滤 SPI 服务

static <T> Optional<T>

loadFirst(Class<T> serviceClass)

Loads the first SPI service implementation 加载第一个 SPI 服务实现

static <T> T

loadFirstOrDefault(Class<T> serviceClass, T defaultValue)

Loads the first SPI service implementation, or uses the default 加载第一个 SPI 服务实现，不存在则使用默认值

static <T> List<T>

loadOrdered(Class<T> serviceClass)

Loads SPI service implementations sorted by priority.

static <T> List<T>

loadSafe(Class<T> serviceClass)

Loads SPI service implementations, skipping any that throw during instantiation.

static <T> List<T>

loadSafe(Class<T> serviceClass, ClassLoader classLoader)

Loads SPI service implementations with error isolation and a specified ClassLoader.

static <T> Stream<T>

loadStream(Class<T> serviceClass)

Lazily loads SPI service implementations as a Stream without eagerly materializing.

static <T> Stream<T>

loadStream(Class<T> serviceClass, ClassLoader classLoader)

Lazily loads SPI service implementations as a Stream with a specified ClassLoader.

static <T> List<T>

reload(Class<T> serviceClass)

Forces reload of SPI services using the context ClassLoader.

static <T> List<T>

reload(Class<T> serviceClass, ClassLoader classLoader)

Forces reload of SPI services atomically using compute to prevent concurrent reload races.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- load
  
  public static <T> List<T> load(Class<T> serviceClass)
  
  Loads SPI service implementations 加载 SPI 服务实现
- load
  
  public static <T> List<T> load(Class<T> serviceClass, ClassLoader classLoader)
  
  Loads SPI service implementations (with specified ClassLoader) 加载 SPI 服务实现（指定类加载器）
- loadFirst
  
  public static <T> Optional<T> loadFirst(Class<T> serviceClass)
  
  Loads the first SPI service implementation 加载第一个 SPI 服务实现
- loadFirstOrDefault
  
  public static <T> T loadFirstOrDefault(Class<T> serviceClass, T defaultValue)
  
  Loads the first SPI service implementation, or uses the default 加载第一个 SPI 服务实现，不存在则使用默认值
- reload
  
  public static <T> List<T> reload(Class<T> serviceClass)
  
  Forces reload of SPI services using the context ClassLoader. 使用上下文类加载器强制重新加载 SPI 服务。
- reload
  
  public static <T> List<T> reload(Class<T> serviceClass, ClassLoader classLoader)
  
  Forces reload of SPI services atomically using compute to prevent concurrent reload races. 使用 compute 原子地强制重新加载 SPI 服务，防止并发 reload 竞争。
  
  Type Parameters:
  
  T - the service type - 服务类型
  
  Parameters:
  
  serviceClass - the service class - 服务类
  
  classLoader - the class loader to use - 使用的类加载器
  
  Returns:
  
  the reloaded list of service implementations - 重新加载的服务实现列表
- hasService
  
  public static <T> boolean hasService(Class<T> serviceClass)
  
  Checks if the SPI service exists 检查 SPI 服务是否存在
- count
  
  public static <T> int count(Class<T> serviceClass)
  
  Gets the SPI service count 获取 SPI 服务数量
- loadByType
  
  public static <T, S extends T> List<S> loadByType(Class<T> serviceClass, Class<S> targetType)
  
  Filters SPI services by type 按类型过滤 SPI 服务
- loadStream
  
  public static <T> Stream<T> loadStream(Class<T> serviceClass)
  
  Lazily loads SPI service implementations as a Stream without eagerly materializing. 延迟加载 SPI 服务实现为 Stream，不会立即实例化所有实现。
  
  Type Parameters:
  
  T - the service type - 服务类型
  
  Parameters:
  
  serviceClass - the service class - 服务类
  
  Returns:
  
  a stream of service implementations - 服务实现的流
- loadStream
  
  public static <T> Stream<T> loadStream(Class<T> serviceClass, ClassLoader classLoader)
  
  Lazily loads SPI service implementations as a Stream with a specified ClassLoader. 使用指定类加载器延迟加载 SPI 服务实现为 Stream。
  
  Type Parameters:
  
  T - the service type - 服务类型
  
  Parameters:
  
  serviceClass - the service class - 服务类
  
  classLoader - the class loader - 类加载器
  
  Returns:
  
  a stream of service implementations - 服务实现的流
- loadSafe
  
  public static <T> List<T> loadSafe(Class<T> serviceClass)
  
  Loads SPI service implementations, skipping any that throw during instantiation. 加载 SPI 服务实现，跳过实例化时抛出异常的实现。
  Unlike load(Class), this method does not cache results and does not throw if a provider fails to instantiate. Failed providers are silently skipped.
  
  与 load(Class) 不同，此方法不缓存结果，且不因提供者实例化失败而抛出异常。失败的提供者被静默跳过。
  
  Type Parameters:
  
  T - the service type | 服务类型
  
  Parameters:
  
  serviceClass - the service interface class | 服务接口类
  
  Returns:
  
  unmodifiable list of successfully loaded services | 成功加载的服务的不可修改列表
- loadSafe
  
  public static <T> List<T> loadSafe(Class<T> serviceClass, ClassLoader classLoader)
  
  Loads SPI service implementations with error isolation and a specified ClassLoader. 使用指定类加载器加载 SPI 服务实现，带错误隔离。
  
  Type Parameters:
  
  T - the service type | 服务类型
  
  Parameters:
  
  serviceClass - the service interface class | 服务接口类
  
  classLoader - the class loader to use | 使用的类加载器
  
  Returns:
  
  unmodifiable list of successfully loaded services | 成功加载的服务的不可修改列表
- loadOrdered
  
  public static <T> List<T> loadOrdered(Class<T> serviceClass)
  
  Loads SPI service implementations sorted by priority. 按优先级排序加载 SPI 服务实现。
  Services with a getPriority() or getOrder() method returning an integer are sorted by that value (lower = higher priority). Services without priority information retain their original loading order.
  
  拥有返回整数的 getPriority() 或 getOrder() 方法的服务按该值排序（值越小优先级越高）。没有优先级信息的服务保持原始加载顺序。
  
  Type Parameters:
  
  T - the service type | 服务类型
  
  Parameters:
  
  serviceClass - the service interface class | 服务接口类
  
  Returns:
  
  unmodifiable ordered list of services | 排序后的服务不可修改列表
- clearCache
  
  public static void clearCache()
  
  Clears the cache 清除缓存
- clearCache
  
  public static void clearCache(Class<?> serviceClass)
  
  Clears the cache for the specified class 清除指定类的缓存

Class SpiLoader

Method Summary

Methods inherited from class Object

Method Details

load

load

loadFirst

loadFirstOrDefault

reload

reload

hasService

count

loadByType

loadStream

loadStream

loadSafe

loadSafe

loadOrdered

clearCache

clearCache