io microsphere util ServiceLoaderUtils

ServiceLoaderUtils

Type: Class | Module: microsphere-java-core | Package: io.microsphere.util | Since: 1.0.0

Source: microsphere-java-core/src/main/java/io/microsphere/util/ServiceLoaderUtils.java

Overview

Utility class for loading and managing service providers via ServiceLoader, with support for caching, prioritization, and ClassLoader hierarchy traversal.

ServiceLoaderUtils provides methods to load all implementations of a service type, retrieve the first or last implementation based on declaration order or priority, and return them as either a list or an array. It supports custom class loaders and optional caching of loaded services.

Key Features

- Load services using the context class loader or a specified class loader.
- Supports caching of loaded services (configurable).
- Sorts services by priority if they implement the `io.microsphere.lang.Prioritized` interface.
- Returns read-only lists or arrays of service instances.

Example Usage

Loading All Services

`List services = ServiceLoaderUtils.loadServicesList(MyService.class);
for (MyService service : services) {
    service.execute();
`
}

Loading First Service (Highest Priority)

`MyService service = ServiceLoaderUtils.loadFirstService(MyService.class);
service.initialize();
`

Loading Last Service (Lowest Priority)

`MyService service = ServiceLoaderUtils.loadLastService(MyService.class);
service.shutdown();
`

Loading With Custom ClassLoader

`ClassLoader cl = MyClassLoader.getInstance();
MyService[] services = ServiceLoaderUtils.loadServices(MyService.class, cl);
`

Loading Without Caching

`List services = ServiceLoaderUtils.loadServicesList(MyService.class, false);
`

Declaration

public abstract class ServiceLoaderUtils implements Utils

Author: Mercy

Version Information

Introduced in: 1.0.0
Current Project Version: 0.3.6-SNAPSHOT

Version Compatibility

This component is tested and compatible with the following Java versions:

Java Version	Status
Java 8	✅ Compatible
Java 11	✅ Compatible
Java 17	✅ Compatible
Java 21	✅ Compatible
Java 25	✅ Compatible

Examples

Example 1

List<MyService> services = ServiceLoaderUtils.loadServicesList(MyService.class);
for (MyService service : services) {
    service.execute();
}

Example 2

MyService service = ServiceLoaderUtils.loadFirstService(MyService.class);
service.initialize();

Example 3

MyService service = ServiceLoaderUtils.loadLastService(MyService.class);
service.shutdown();

Example 4

ClassLoader cl = MyClassLoader.getInstance();
MyService[] services = ServiceLoaderUtils.loadServices(MyService.class, cl);

Example 5

List<MyService> services = ServiceLoaderUtils.loadServicesList(MyService.class, false);

Method Examples

`getServiceClasses`

Set<Class<MyService>> classes = ServiceLoaderUtils.getServiceClasses(MyService.class);
for (Class<MyService> clazz : classes) {
    System.out.println("Found service implementation class: " + clazz.getName());
}

`getServiceClasses`

// Fail fast if a class cannot be loaded or is not assignable
Set<Class<MyService>> classes = ServiceLoaderUtils.getServiceClasses(MyService.class, true);
for (Class<MyService> clazz : classes) {
    System.out.println("Found service implementation class: " + clazz.getName());
}

// Lenient mode: skip invalid classes
Set<Class<MyService>> lenientClasses = ServiceLoaderUtils.getServiceClasses(MyService.class, false);

`getServiceClasses`

ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
Set<Class<MyService>> classes = ServiceLoaderUtils.getServiceClasses(MyService.class, classLoader);
for (Class<MyService> clazz : classes) {
    System.out.println("Found service implementation class: " + clazz.getName());
}

`getServiceClasses`

ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
// Fail fast if a class cannot be loaded or is not assignable
Set<Class<MyService>> classes = ServiceLoaderUtils.getServiceClasses(MyService.class, classLoader, true);
for (Class<MyService> clazz : classes) {
    System.out.println("Found service implementation class: " + clazz.getName());
}

// Lenient mode: skip invalid classes
Set<Class<MyService>> lenientClasses = ServiceLoaderUtils.getServiceClasses(MyService.class, classLoader, false);

`getServiceClassNames`

Set<String> classNames = ServiceLoaderUtils.getServiceClassNames(MyService.class);
for (String className : classNames) {
    System.out.println("Found service implementation: " + className);
}

`getServiceClassNames`

ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
Set<String> classNames = ServiceLoaderUtils.getServiceClassNames(MyService.class, classLoader);
for (String className : classNames) {
    System.out.println("Found service implementation: " + className);
}

`getServiceResoources`

ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
Set<URL> resources = ServiceLoaderUtils.getServiceResources(MyService.class, classLoader);
for (URL url : resources) {
    System.out.println("Found service config at: " + url);
}

`loadServicesList`

List<MyService> services = ServiceLoaderUtils.loadServicesList(MyService.class);
for (MyService service : services) {
    service.execute();
}

`loadServicesList`

ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
List<MyService> services = ServiceLoaderUtils.loadServicesList(MyService.class, classLoader);
for (MyService service : services) {
    service.execute();
}

`loadServicesList`

List<MyService> services = ServiceLoaderUtils.loadServicesList(MyService.class, true);
for (MyService service : services) {
    service.execute();
}

`loadServicesList`

ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
List<MyService> services = ServiceLoaderUtils.loadServicesList(MyService.class, classLoader, true);
for (MyService service : services) {
    service.execute();
}

`loadServices`

MyService[] services = ServiceLoaderUtils.loadServices(MyService.class);
for (MyService service : services) {
    service.execute();
}

`loadServices`

ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
MyService[] services = ServiceLoaderUtils.loadServices(MyService.class, classLoader);
for (MyService service : services) {
    service.execute();
}

`loadServices`

MyService[] services = ServiceLoaderUtils.loadServices(MyService.class, true);
for (MyService service : services) {
    service.initialize();
}

`loadServices`

ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
MyService[] services = ServiceLoaderUtils.loadServices(MyService.class, classLoader, true);
for (MyService service : services) {
    service.execute();
}

`loadFirstService`

MyService service = ServiceLoaderUtils.loadFirstService(MyService.class);
if (service != null) {
    service.execute();
}

`loadFirstService`

MyService service = ServiceLoaderUtils.loadFirstService(MyService.class, true);
if (service != null) {
    service.initialize();
}

`loadFirstService`

ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
MyService service = ServiceLoaderUtils.loadFirstService(MyService.class, classLoader);
if (service != null) {
    service.execute();
}

`loadFirstService`

ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
MyService service = ServiceLoaderUtils.loadFirstService(MyService.class, classLoader, true);
if (service != null) {
    service.initialize();
}

`loadLastService`

MyService service = ServiceLoaderUtils.loadLastService(MyService.class);
if (service != null) {
    service.execute();
}

Usage

Maven Dependency

Add the following dependency to your pom.xml:

<dependency>
    <groupId>io.github.microsphere-projects</groupId>
    <artifactId>microsphere-java-core</artifactId>
    <version>${microsphere-java.version}</version>
</dependency>

Tip: Use the BOM (microsphere-java-dependencies) for consistent version management. See the Getting Started guide.

Import

import io.microsphere.util.ServiceLoaderUtils;

API Reference

Public Methods

Method	Description
`getServiceClasses`	The default value of the `#SERVICE_LOADER_CACHED` property : `"false"`
`getServiceClasses`	Retrieves the implementation classes of all service providers for the specified service type using the context class ...
`getServiceClasses`	Retrieves the implementation classes of all service providers for the specified service type using the provided `Clas...
`getServiceClasses`	Retrieves the implementation classes of all service providers for the specified service type.
`getServiceClassNames`	Retrieves the class names of all service providers for the specified service type using the context class loader.
`getServiceClassNames`	Retrieves the class names of all service providers for the specified service type.
`getServiceResoources`	Retrieves the URLs of the service provider configuration files for the specified service type.
`loadServicesList`	Loads all implementation instances of the specified `ServiceLoader` service type using the context class loader.
`loadServicesList`	Loads all implementation instances of the specified `ServiceLoader` service type using the provided `ClassLoader`.
`loadServicesList`	Loads all implementation instances of the specified `ServiceLoader` service type using the context class loader,
`loadServicesList`	Loads all implementation instances of the specified `ServiceLoader` service type using the provided `ClassLoader`,
`loadServices`	Loads all implementation instances of the specified `ServiceLoader` service type using the context class loader.
`loadServices`	Loads all implementation instances of the specified `ServiceLoader` service type using the provided `ClassLoader`.
`loadServices`	Loads all implementation instances of the specified `ServiceLoader` service type using the context class loader,
`loadServices`	Loads all implementation instances of the specified `ServiceLoader` service type using the provided `ClassLoader`,
`loadFirstService`	Loads the first instance of the specified `ServiceLoader` service type using the context class loader.
`loadFirstService`	Loads the first instance of the specified `ServiceLoader` service type using the context class loader,
`loadFirstService`	Loads the first instance of the specified `ServiceLoader` service type using the provided `ClassLoader`.
`loadFirstService`	Loads the first instance of the specified `ServiceLoader` service type using the provided `ClassLoader`,
`loadLastService`	Loads the last instance of the specified `ServiceLoader` service type using the context class loader.

Method Details

`getServiceClasses`

public static <T> Set<Class<T>> getServiceClasses(Class<T> serviceType)

The default value of the #SERVICE_LOADER_CACHED property : "false" / public static final String DEFAULT_SERVICE_LOADER_CACHED_PROPERTY_VALUE = "false";

/** The name of the #SERVICE_LOADER_CACHED property : "microsphere.service-loader.cached" / public static final String SERVICE_LOADER_CACHED_PROPERTY_NAME = MICROSPHERE_PROPERTY_NAME_PREFIX + "service-loader.cached";

/** The location of service provider configuration files : "META-INF/services/".

`getServiceClasses`

public static <T> Set<Class<T>> getServiceClasses(Class<T> serviceType, boolean failFast)

Retrieves the implementation classes of all service providers for the specified service type using the context class loader.

This method searches for service provider configuration files located at META-INF/services/ using the context class loader associated with the service type. It loads the classes defined in these configuration files and verifies their assignability to the service type.

Example Usage

`// Fail fast if a class cannot be loaded or is not assignable
Set> classes = ServiceLoaderUtils.getServiceClasses(MyService.class, true);
for (Class clazz : classes) {
    System.out.println("Found service implementation class: " + clazz.getName());
`

// Lenient mode: skip invalid classes
Set> lenientClasses = ServiceLoaderUtils.getServiceClasses(MyService.class, false);
}

`getServiceClasses`

public static <T> Set<Class<T>> getServiceClasses(Class<T> serviceType, @Nullable ClassLoader classLoader)

Retrieves the implementation classes of all service providers for the specified service type using the provided ClassLoader.

This method searches for service provider configuration files located at META-INF/services/ using the provided ClassLoader. It loads the classes defined in these configuration files and verifies their assignability to the service type. This method uses the default fail-fast behavior (true).

Example Usage

`ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
Set> classes = ServiceLoaderUtils.getServiceClasses(MyService.class, classLoader);
for (Class clazz : classes) {
    System.out.println("Found service implementation class: " + clazz.getName());
`
}

`getServiceClasses`

public static <T> Set<Class<T>> getServiceClasses(Class<T> serviceType, @Nullable ClassLoader classLoader, boolean failFast)

Retrieves the implementation classes of all service providers for the specified service type.

This method searches for service provider configuration files located at META-INF/services/ using the provided ClassLoader. It loads the classes defined in these configuration files and verifies their assignability to the service type.

Example Usage

`ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
// Fail fast if a class cannot be loaded or is not assignable
Set> classes = ServiceLoaderUtils.getServiceClasses(MyService.class, classLoader, true);
for (Class clazz : classes) {
    System.out.println("Found service implementation class: " + clazz.getName());
`

// Lenient mode: skip invalid classes
Set> lenientClasses = ServiceLoaderUtils.getServiceClasses(MyService.class, classLoader, false);
}

`getServiceClassNames`

public static Set<String> getServiceClassNames(Class<?> serviceType)

Retrieves the class names of all service providers for the specified service type using the context class loader.

This method searches for service provider configuration files located at META-INF/services/ using the context class loader associated with the service type. It reads the fully qualified class names defined in these configuration files.

Example Usage

`Set classNames = ServiceLoaderUtils.getServiceClassNames(MyService.class);
for (String className : classNames) {
    System.out.println("Found service implementation: " + className);
`
}

`getServiceClassNames`

public static Set<String> getServiceClassNames(Class<?> serviceType, @Nullable ClassLoader classLoader)

Retrieves the class names of all service providers for the specified service type.

This method searches for service provider configuration files located at META-INF/services/ using the provided ClassLoader. It reads the fully qualified class names defined in these configuration files.

Example Usage

`ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
Set classNames = ServiceLoaderUtils.getServiceClassNames(MyService.class, classLoader);
for (String className : classNames) {
    System.out.println("Found service implementation: " + className);
`
}

`getServiceResoources`

public static Set<URL> getServiceResoources(Class<?> serviceType, @Nullable ClassLoader classLoader)

Retrieves the URLs of the service provider configuration files for the specified service type.

This method searches for configuration files located at META-INF/services/ using the provided ClassLoader. It traverses the class loader hierarchy to find all matching resources.

Example Usage

`ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
Set resources = ServiceLoaderUtils.getServiceResources(MyService.class, classLoader);
for (URL url : resources) {
    System.out.println("Found service config at: " + url);
`
}

`loadServicesList`

public static <S> List<S> loadServicesList(Class<S> serviceType)

Loads all implementation instances of the specified ServiceLoader service type using the context class loader.

This method traverses the hierarchy of ClassLoader to load the service configuration file located at /META-INF/services/. The returned list contains all discovered implementations in the order they were found, sorted by their priority if they implement the io.microsphere.lang.Prioritized interface.

Example Usage

`List services = ServiceLoaderUtils.loadServicesList(MyService.class);
for (MyService service : services) {
    service.execute();
`
}

`loadServicesList`

public static <S> List<S> loadServicesList(Class<S> serviceType, @Nullable ClassLoader classLoader)

Loads all implementation instances of the specified ServiceLoader service type using the provided ClassLoader.

This method traverses the hierarchy of ClassLoader to load the service configuration file located at /META-INF/services/. The returned list contains all discovered implementations in the order they were found, sorted by their priority if they implement the io.microsphere.lang.Prioritized interface.

Example Usage

`ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
List services = ServiceLoaderUtils.loadServicesList(MyService.class, classLoader);
for (MyService service : services) {
    service.execute();
`
}

`loadServicesList`

public static <S> List<S> loadServicesList(Class<S> serviceType, boolean cached)

Loads all implementation instances of the specified ServiceLoader service type using the context class loader, with an option to enable or disable caching of the loaded services.

This method traverses the hierarchy of ClassLoader to load the service configuration file located at /META-INF/services/. The returned list contains all discovered implementations in the order they were found, sorted by their priority if they implement the io.microsphere.lang.Prioritized interface.

Example Usage

`List services = ServiceLoaderUtils.loadServicesList(MyService.class, true);
for (MyService service : services) {
    service.execute();
`
}

`loadServicesList`

public static <S> List<S> loadServicesList(Class<S> serviceType, @Nullable ClassLoader classLoader, boolean cached)

Loads all implementation instances of the specified ServiceLoader service type using the provided ClassLoader, with an option to enable or disable caching of the loaded services.

This method traverses the hierarchy of ClassLoader to load the service configuration file located at /META-INF/services/. The returned list contains all discovered implementations in the order they were found, sorted by their priority if they implement the io.microsphere.lang.Prioritized interface.

Example Usage

`ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
List services = ServiceLoaderUtils.loadServicesList(MyService.class, classLoader, true);
for (MyService service : services) {
    service.execute();
`
}

`loadServices`

public static <S> S[] loadServices(Class<S> serviceType)

Loads all implementation instances of the specified ServiceLoader service type using the context class loader.

This method traverses the hierarchy of ClassLoader to load the service configuration file located at /META-INF/services/. The returned array contains all discovered implementations in the order they were found, sorted by their priority if they implement the io.microsphere.lang.Prioritized interface.

Example Usage

`MyService[] services = ServiceLoaderUtils.loadServices(MyService.class);
for (MyService service : services) {
    service.execute();
`
}

`loadServices`

public static <S> S[] loadServices(Class<S> serviceType, @Nullable ClassLoader classLoader)

Loads all implementation instances of the specified ServiceLoader service type using the provided ClassLoader.

This method traverses the hierarchy of ClassLoader to load the service configuration file located at /META-INF/services/. The returned array contains all discovered implementations in the order they were found, sorted by their priority if they implement the io.microsphere.lang.Prioritized interface.

Example Usage

`ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
MyService[] services = ServiceLoaderUtils.loadServices(MyService.class, classLoader);
for (MyService service : services) {
    service.execute();
`
}

`loadServices`

public static <S> S[] loadServices(Class<S> serviceType, boolean cached)

Loads all implementation instances of the specified ServiceLoader service type using the context class loader, with an option to enable or disable caching of the loaded services.

This method utilizes the context class loader associated with the provided service type to load the service configuration file located at /META-INF/services/. The returned array contains all discovered implementations in the order they were found, sorted by their priority if they implement the io.microsphere.lang.Prioritized interface.

Example Usage

`MyService[] services = ServiceLoaderUtils.loadServices(MyService.class, true);
for (MyService service : services) {
    service.initialize();
`
}

`loadServices`

public static <S> S[] loadServices(Class<S> serviceType, @Nullable ClassLoader classLoader, boolean cached)

Loads all implementation instances of the specified ServiceLoader service type using the provided ClassLoader, with an option to enable or disable caching of the loaded services.

This method traverses the hierarchy of ClassLoader to load the service configuration file located at /META-INF/services/. The returned array contains all discovered implementations in the order they were found, sorted by their priority if they implement the io.microsphere.lang.Prioritized interface.

Example Usage

`ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
MyService[] services = ServiceLoaderUtils.loadServices(MyService.class, classLoader, true);
for (MyService service : services) {
    service.execute();
`
}

`loadFirstService`

public static <S> S loadFirstService(Class<S> serviceType)

Loads the first instance of the specified ServiceLoader service type using the context class loader.

This method retrieves the list of service implementations using #loadServicesList(Class, ClassLoader), and returns the first element from the list. The order of service instances is determined by their declaration in the configuration files, and services implementing the io.microsphere.lang.Prioritized interface are sorted by priority.

Example Usage

`MyService service = ServiceLoaderUtils.loadFirstService(MyService.class);
if (service != null) {
    service.execute();
`
}

`loadFirstService`

public static <S> S loadFirstService(Class<S> serviceType, boolean cached)

Loads the first instance of the specified ServiceLoader service type using the context class loader, with an option to enable or disable caching of the loaded services.

This method retrieves the list of service implementations using #loadServicesList(Class, ClassLoader, boolean), and returns the first element from the list. The order of service instances is determined by their declaration in the configuration files, and services implementing the io.microsphere.lang.Prioritized interface are sorted by priority.

Design Purpose : Using the hierarchy of ClassLoader, each level of ClassLoader will be able to access the configuration files under its class path /META-INF/services/serviceType. Then, override the first implementation class of the configuration file under the class path of ClassLoader, thereby providing a mechanism for overriding the implementation class.

Example Usage

`MyService service = ServiceLoaderUtils.loadFirstService(MyService.class, true);
if (service != null) {
    service.initialize();
`
}

`loadFirstService`

public static <S> S loadFirstService(Class<S> serviceType, @Nullable ClassLoader classLoader)

Loads the first instance of the specified ServiceLoader service type using the provided ClassLoader.

This method retrieves the list of service implementations using #loadServicesList(Class, ClassLoader), and returns the first element from the list. The order of service instances is determined by their declaration in the configuration files, and services implementing the io.microsphere.lang.Prioritized interface are sorted by priority.

Example Usage

`ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
MyService service = ServiceLoaderUtils.loadFirstService(MyService.class, classLoader);
if (service != null) {
    service.execute();
`
}

`loadFirstService`

public static <S> S loadFirstService(Class<S> serviceType, @Nullable ClassLoader classLoader, boolean cached)

Loads the first instance of the specified ServiceLoader service type using the provided ClassLoader, with an option to enable or disable caching of the loaded services.

This method retrieves the list of service implementations using #loadServicesList(Class, ClassLoader, boolean), and returns the first element from the list. The order of service instances is determined by their declaration in the configuration files, and services implementing the io.microsphere.lang.Prioritized interface are sorted by priority.

Example Usage

`ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
MyService service = ServiceLoaderUtils.loadFirstService(MyService.class, classLoader, true);
if (service != null) {
    service.initialize();
`
}

`loadLastService`

public static <S> S loadLastService(Class<S> serviceType)

Loads the last instance of the specified ServiceLoader service type using the context class loader.

This method retrieves the list of service implementations using #loadServicesList(Class, ClassLoader), and returns the last element from the list. The order of service instances is determined by their declaration in the configuration files, and services implementing the io.microsphere.lang.Prioritized interface are sorted by priority.

Example Usage

`MyService service = ServiceLoaderUtils.loadLastService(MyService.class);
if (service != null) {
    service.execute();
`
}