Package io.microsphere.util

Class ServiceLoaderUtils

  • All Implemented Interfaces:
    Utils
    public abstract class ServiceLoaderUtils
extends java.lang.Object
implements Utils
    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 Prioritized interface.
    • Returns read-only lists or arrays of service instances.

    Example Usage

    Loading All Services

    
 List<MyService> 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<MyService> services = ServiceLoaderUtils.loadServicesList(MyService.class, false);
    Since:
    1.0.0
    Author:
    Mercy
    See Also:
    ServiceLoader

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <S> S loadFirstService​(java.lang.Class<S> serviceType)
      Loads the first instance of the specified ServiceLoader service type using the context class loader.
      static <S> S loadFirstService​(java.lang.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.
      static <S> S loadFirstService​(java.lang.Class<S> serviceType, java.lang.ClassLoader classLoader)
      Loads the first instance of the specified ServiceLoader service type using the provided ClassLoader.
      static <S> S loadFirstService​(java.lang.Class<S> serviceType, java.lang.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.
      static <S> S loadLastService​(java.lang.Class<S> serviceType)
      Loads the last instance of the specified ServiceLoader service type using the context class loader.
      static <S> S loadLastService​(java.lang.Class<S> serviceType, boolean cached)
      Loads the last instance of the specified ServiceLoader service type using the context class loader, with an option to enable or disable caching of the loaded services.
      static <S> S loadLastService​(java.lang.Class<S> serviceType, java.lang.ClassLoader classLoader)
      Loads the last instance of the specified ServiceLoader service type using the provided ClassLoader.
      static <S> S loadLastService​(java.lang.Class<S> serviceType, java.lang.ClassLoader classLoader, boolean cached)
      Loads the last instance of the specified ServiceLoader service type using the provided ClassLoader, with an option to enable or disable caching of the loaded services.
      static <S> S[] loadServices​(java.lang.Class<S> serviceType)
      Loads all implementation instances of the specified ServiceLoader service type using the context class loader.
      static <S> S[] loadServices​(java.lang.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.
      static <S> S[] loadServices​(java.lang.Class<S> serviceType, java.lang.ClassLoader classLoader)
      Loads all implementation instances of the specified ServiceLoader service type using the provided ClassLoader.
      static <S> S[] loadServices​(java.lang.Class<S> serviceType, java.lang.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.
      static <S> java.util.List<S> loadServicesList​(java.lang.Class<S> serviceType)
      Loads all implementation instances of the specified ServiceLoader service type using the context class loader.
      static <S> java.util.List<S> loadServicesList​(java.lang.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.
      static <S> java.util.List<S> loadServicesList​(java.lang.Class<S> serviceType, java.lang.ClassLoader classLoader)
      Loads all implementation instances of the specified ServiceLoader service type using the provided ClassLoader.
      static <S> java.util.List<S> loadServicesList​(java.lang.Class<S> serviceType, java.lang.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.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • loadServicesList

        @Nonnull
public static <S> java.util.List<S> loadServicesList​(java.lang.Class<S> serviceType)
                                              throws java.lang.IllegalArgumentException
        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/<serviceType>. The returned list contains all discovered implementations in the order they were found, sorted by their priority if they implement the Prioritized interface.

        Usage Example

        
 List<MyService> services = ServiceLoaderUtils.loadServicesList(MyService.class);
 for (MyService service : services) {
     service.execute();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        Returns:
        a read-only list containing all implementation instances of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadServicesList

        @Nonnull
public static <S> java.util.List<S> loadServicesList​(java.lang.Class<S> serviceType,
                                                     @Nullable
                                                     java.lang.ClassLoader classLoader)
                                              throws java.lang.IllegalArgumentException
        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/<serviceType>. The returned list contains all discovered implementations in the order they were found, sorted by their priority if they implement the Prioritized interface.

        Usage Example

        
 ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
 List<MyService> services = ServiceLoaderUtils.loadServicesList(MyService.class, classLoader);
 for (MyService service : services) {
     service.execute();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        classLoader - the class loader used to load service implementations; must not be null
        Returns:
        a read-only list containing all implementation instances of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadServicesList

        @Nonnull
public static <S> java.util.List<S> loadServicesList​(java.lang.Class<S> serviceType,
                                                     boolean cached)
                                              throws java.lang.IllegalArgumentException
        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/<serviceType>. The returned list contains all discovered implementations in the order they were found, sorted by their priority if they implement the Prioritized interface.

        Usage Example

        
 List<MyService> services = ServiceLoaderUtils.loadServicesList(MyService.class, true);
 for (MyService service : services) {
     service.execute();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        cached - flag indicating whether to cache the loaded services
        Returns:
        a read-only list containing all implementation instances of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadServicesList

        @Nonnull
public static <S> java.util.List<S> loadServicesList​(java.lang.Class<S> serviceType,
                                                     @Nullable
                                                     java.lang.ClassLoader classLoader,
                                                     boolean cached)
                                              throws java.lang.IllegalArgumentException
        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/<serviceType>. The returned list contains all discovered implementations in the order they were found, sorted by their priority if they implement the Prioritized interface.

        Usage Example

        
 ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
 List<MyService> services = ServiceLoaderUtils.loadServicesList(MyService.class, classLoader, true);
 for (MyService service : services) {
     service.execute();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        classLoader - the class loader used to load service implementations; must not be null
        cached - flag indicating whether to cache the loaded services
        Returns:
        a read-only list containing all implementation instances of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadServices

        @Nonnull
public static <S> S[] loadServices​(java.lang.Class<S> serviceType)
                            throws java.lang.IllegalArgumentException
        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/<serviceType>. The returned array contains all discovered implementations in the order they were found, sorted by their priority if they implement the Prioritized interface.

        Usage Example

        
 MyService[] services = ServiceLoaderUtils.loadServices(MyService.class);
 for (MyService service : services) {
     service.execute();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        Returns:
        an array containing all implementation instances of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadServices

        @Nonnull
public static <S> S[] loadServices​(java.lang.Class<S> serviceType,
                                   @Nullable
                                   java.lang.ClassLoader classLoader)
                            throws java.lang.IllegalArgumentException
        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/<serviceType>. The returned array contains all discovered implementations in the order they were found, sorted by their priority if they implement the Prioritized interface.

        Usage Example

        
 ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
 MyService[] services = ServiceLoaderUtils.loadServices(MyService.class, classLoader);
 for (MyService service : services) {
     service.execute();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        classLoader - the class loader used to load service implementations; must not be null
        Returns:
        an array containing all implementation instances of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadServices

        @Nonnull
public static <S> S[] loadServices​(java.lang.Class<S> serviceType,
                                   boolean cached)
                            throws java.lang.IllegalArgumentException
        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/<serviceType>. The returned array contains all discovered implementations in the order they were found, sorted by their priority if they implement the Prioritized interface.

        Usage Example

        
 MyService[] services = ServiceLoaderUtils.loadServices(MyService.class, true);
 for (MyService service : services) {
     service.initialize();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        cached - flag indicating whether to cache the loaded services
        Returns:
        an array containing all implementation instances of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadServices

        @Nonnull
public static <S> S[] loadServices​(java.lang.Class<S> serviceType,
                                   @Nullable
                                   java.lang.ClassLoader classLoader,
                                   boolean cached)
                            throws java.lang.IllegalArgumentException
        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/<serviceType>. The returned array contains all discovered implementations in the order they were found, sorted by their priority if they implement the Prioritized interface.

        Usage Example

        
 ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
 MyService[] services = ServiceLoaderUtils.loadServices(MyService.class, classLoader, true);
 for (MyService service : services) {
     service.execute();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        classLoader - the class loader used to load service implementations; must not be null
        cached - flag indicating whether to cache the loaded services
        Returns:
        an array containing all implementation instances of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadFirstService

        @Nonnull
public static <S> S loadFirstService​(java.lang.Class<S> serviceType)
                              throws java.lang.IllegalArgumentException
        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 Prioritized interface are sorted by priority.

        Usage Example

        
 MyService service = ServiceLoaderUtils.loadFirstService(MyService.class);
 if (service != null) {
     service.execute();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        Returns:
        the first implementation instance of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadFirstService

        @Nonnull
public static <S> S loadFirstService​(java.lang.Class<S> serviceType,
                                     boolean cached)
                              throws java.lang.IllegalArgumentException
        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 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.

        Usage Example

        
 MyService service = ServiceLoaderUtils.loadFirstService(MyService.class, true);
 if (service != null) {
     service.initialize();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        cached - flag indicating whether to cache the loaded services
        Returns:
        the first implementation instance of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadFirstService

        @Nonnull
public static <S> S loadFirstService​(java.lang.Class<S> serviceType,
                                     @Nullable
                                     java.lang.ClassLoader classLoader)
                              throws java.lang.IllegalArgumentException
        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 Prioritized interface are sorted by priority.

        Usage Example

        
 ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
 MyService service = ServiceLoaderUtils.loadFirstService(MyService.class, classLoader);
 if (service != null) {
     service.execute();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        classLoader - the class loader used to load service implementations; must not be null
        Returns:
        the first implementation instance of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadFirstService

        @Nonnull
public static <S> S loadFirstService​(java.lang.Class<S> serviceType,
                                     @Nullable
                                     java.lang.ClassLoader classLoader,
                                     boolean cached)
                              throws java.lang.IllegalArgumentException
        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 Prioritized interface are sorted by priority.

        Usage Example

        
 ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
 MyService service = ServiceLoaderUtils.loadFirstService(MyService.class, classLoader, true);
 if (service != null) {
     service.initialize();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        classLoader - the class loader used to load service implementations; must not be null
        cached - flag indicating whether to cache the loaded services
        Returns:
        the first implementation instance of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadLastService

        @Nonnull
public static <S> S loadLastService​(java.lang.Class<S> serviceType)
                             throws java.lang.IllegalArgumentException
        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 Prioritized interface are sorted by priority.

        Usage Example

        
 MyService service = ServiceLoaderUtils.loadLastService(MyService.class);
 if (service != null) {
     service.execute();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        Returns:
        the last implementation instance of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadLastService

        @Nonnull
public static <S> S loadLastService​(java.lang.Class<S> serviceType,
                                    boolean cached)
                             throws java.lang.IllegalArgumentException
        Loads the last 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 last element from the list. The order of service instances is determined by their declaration in the configuration files, and services implementing the Prioritized interface are sorted by priority.

        Usage Example

        
 MyService service = ServiceLoaderUtils.loadLastService(MyService.class, true);
 if (service != null) {
     service.initialize();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        cached - flag indicating whether to cache the loaded services
        Returns:
        the last implementation instance of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadLastService

        @Nonnull
public static <S> S loadLastService​(java.lang.Class<S> serviceType,
                                    @Nullable
                                    java.lang.ClassLoader classLoader)
                             throws java.lang.IllegalArgumentException
        Loads the last 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 last element from the list. The order of service instances is determined by their declaration in the configuration files, and services implementing the Prioritized interface are sorted by priority.

        Usage Example

        
 ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
 MyService service = ServiceLoaderUtils.loadLastService(MyService.class, classLoader);
 if (service != null) {
     service.execute();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        classLoader - the class loader used to load service implementations; must not be null
        Returns:
        the last implementation instance of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file

      • loadLastService

        @Nonnull
public static <S> S loadLastService​(java.lang.Class<S> serviceType,
                                    @Nullable
                                    java.lang.ClassLoader classLoader,
                                    boolean cached)
                             throws java.lang.IllegalArgumentException
        Loads the last 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 last element from the list. The order of service instances is determined by their declaration in the configuration files, and services implementing the Prioritized interface are sorted by priority.

        Usage Example

        
 ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
 MyService service = ServiceLoaderUtils.loadLastService(MyService.class, classLoader, true);
 if (service != null) {
     service.initialize();
 }
        Type Parameters:
        S - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        classLoader - the class loader used to load service implementations; must not be null
        cached - flag indicating whether to cache the loaded services
        Returns:
        the last implementation instance of the service type
        Throws:
        java.lang.IllegalArgumentException - if no implementation is defined for the service type in the configuration file