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 <T> java.util.Set<java.lang.Class<T>> getServiceClasses​(java.lang.Class<T> serviceType)
      Retrieves the implementation classes of all service providers for the specified service type using the context class loader.
      static <T> java.util.Set<java.lang.Class<T>> getServiceClasses​(java.lang.Class<T> serviceType, boolean failFast)
      Retrieves the implementation classes of all service providers for the specified service type using the context class loader.
      static <T> java.util.Set<java.lang.Class<T>> getServiceClasses​(java.lang.Class<T> serviceType, java.lang.ClassLoader classLoader)
      Retrieves the implementation classes of all service providers for the specified service type using the provided ClassLoader.
      static <T> java.util.Set<java.lang.Class<T>> getServiceClasses​(java.lang.Class<T> serviceType, java.lang.ClassLoader classLoader, boolean failFast)
      Retrieves the implementation classes of all service providers for the specified service type.
      static java.util.Set<java.lang.String> getServiceClassNames​(java.lang.Class<?> serviceType)
      Retrieves the class names of all service providers for the specified service type using the context class loader.
      static java.util.Set<java.lang.String> getServiceClassNames​(java.lang.Class<?> serviceType, java.lang.ClassLoader classLoader)
      Retrieves the class names of all service providers for the specified service type.
      static java.util.Set<java.net.URL> getServiceResoources​(java.lang.Class<?> serviceType, java.lang.ClassLoader classLoader)
      Retrieves the URLs of the service provider configuration files for the specified service type.
      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

    • Field Detail

      • DEFAULT_SERVICE_LOADER_CACHED_PROPERTY_VALUE

        public static final java.lang.String DEFAULT_SERVICE_LOADER_CACHED_PROPERTY_VALUE
        The default value of the SERVICE_LOADER_CACHED property : "false"
        See Also:
        Constant Field Values

      • SERVICE_LOADER_CACHED_PROPERTY_NAME

        public static final java.lang.String SERVICE_LOADER_CACHED_PROPERTY_NAME
        The name of the SERVICE_LOADER_CACHED property : "microsphere.service-loader.cached"
        See Also:
        Constant Field Values

      • SERVICES_PROVIDER_LOCATION

        public static final java.lang.String SERVICES_PROVIDER_LOCATION
        The location of service provider configuration files : "META-INF/services/".
        See Also:
        ServiceLoader, Constant Field Values

      • SERVICE_PROVIDER_CONFIG_FILES_LOCATION_PATTERN

        public static final java.lang.String SERVICE_PROVIDER_CONFIG_FILES_LOCATION_PATTERN
        The locatings' pattern of configuration files of the single service provider : "META-INF/services/{}", where "{}" is replaced with the service type name.
        See Also:
        ServiceLoader, Constant Field Values

      • SERVICE_LOADER_CACHED

        @ConfigurationProperty(name="microsphere.service-loader.cached",
                       defaultValue="false",
                       description="Whether to cache the loaded services",
                       source="system-properties")
public static final boolean SERVICE_LOADER_CACHED
        Whether to cache the loaded services

    • Method Detail

      • getServiceClasses

        @Nonnull
@Immutable
public static <T> java.util.Set<java.lang.Class<T>> getServiceClasses​(java.lang.Class<T> serviceType)
        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/<serviceType> 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. This method uses the default fail-fast behavior (true).

        Example Usage

        
 Set<Class<MyService>> classes = ServiceLoaderUtils.getServiceClasses(MyService.class);
 for (Class<MyService> clazz : classes) {
     System.out.println("Found service implementation class: " + clazz.getName());
 }
        Type Parameters:
        T - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        Returns:
        an unmodifiable set of implementation classes of the service providers
        Throws:
        java.lang.IllegalStateException - if a class cannot be loaded or is not assignable to the service type

      • getServiceClasses

        @Nonnull
@Immutable
public static <T> java.util.Set<java.lang.Class<T>> getServiceClasses​(java.lang.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/<serviceType> 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<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);
        Type Parameters:
        T - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        failFast - if true, throws an exception when a class cannot be loaded or is not assignable; if false, skips invalid classes
        Returns:
        an unmodifiable set of implementation classes of the service providers
        Throws:
        java.lang.IllegalStateException - if failFast is true and an error occurs during loading or assignment check

      • getServiceClasses

        @Nonnull
@Immutable
public static <T> java.util.Set<java.lang.Class<T>> getServiceClasses​(java.lang.Class<T> serviceType,
                                                                      @Nullable
                                                                      java.lang.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/<serviceType> 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<Class<MyService>> classes = ServiceLoaderUtils.getServiceClasses(MyService.class, classLoader);
 for (Class<MyService> clazz : classes) {
     System.out.println("Found service implementation class: " + clazz.getName());
 }
        Type Parameters:
        T - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        classLoader - the class loader used to locate and load the resources; may be null
        Returns:
        an unmodifiable set of implementation classes of the service providers
        Throws:
        java.lang.IllegalStateException - if a class cannot be loaded or is not assignable to the service type

      • getServiceClasses

        @Nonnull
@Immutable
public static <T> java.util.Set<java.lang.Class<T>> getServiceClasses​(java.lang.Class<T> serviceType,
                                                                      @Nullable
                                                                      java.lang.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/<serviceType> 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<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);
        Type Parameters:
        T - the service type
        Parameters:
        serviceType - the class of the service type, cannot be null
        classLoader - the class loader used to locate and load the resources; may be null
        failFast - if true, throws an exception when a class cannot be loaded or is not assignable; if false, skips invalid classes
        Returns:
        an unmodifiable set of implementation classes of the service providers
        Throws:
        java.lang.IllegalStateException - if failFast is true and an error occurs during loading or assignment check

      • getServiceClassNames

        @Nonnull
@Immutable
public static java.util.Set<java.lang.String> getServiceClassNames​(java.lang.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/<serviceType> 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<String> classNames = ServiceLoaderUtils.getServiceClassNames(MyService.class);
 for (String className : classNames) {
     System.out.println("Found service implementation: " + className);
 }
        Parameters:
        serviceType - the class of the service type, cannot be null
        Returns:
        an unmodifiable set of fully qualified class names of the service providers

      • getServiceClassNames

        @Nonnull
@Immutable
public static java.util.Set<java.lang.String> getServiceClassNames​(java.lang.Class<?> serviceType,
                                                                   @Nullable
                                                                   java.lang.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/<serviceType> using the provided ClassLoader. It reads the fully qualified class names defined in these configuration files.

        Example Usage

        
 ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
 Set<String> classNames = ServiceLoaderUtils.getServiceClassNames(MyService.class, classLoader);
 for (String className : classNames) {
     System.out.println("Found service implementation: " + className);
 }
        Parameters:
        serviceType - the class of the service type, cannot be null
        classLoader - the class loader used to locate the resources; may be null
        Returns:
        an unmodifiable set of fully qualified class names of the service providers

      • getServiceResoources

        @Nonnull
@Immutable
public static java.util.Set<java.net.URL> getServiceResoources​(java.lang.Class<?> serviceType,
                                                               @Nullable
                                                               java.lang.ClassLoader classLoader)
                                                        throws java.io.IOException
        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/<serviceType> using the provided ClassLoader. It traverses the class loader hierarchy to find all matching resources.

        Example Usage

        
 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);
 }
        Parameters:
        serviceType - the class of the service type, cannot be null
        classLoader - the class loader used to locate the resources; may be null
        Returns:
        a set of URLs pointing to the service provider configuration files
        Throws:
        java.io.IOException - if an I/O error occurs while accessing the resources

      • loadServicesList

        @Nonnull
@Immutable
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.

        Example Usage

        
 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
@Immutable
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.

        Example Usage

        
 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
@Immutable
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.

        Example Usage

        
 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
@Immutable
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.

        Example Usage

        
 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.

        Example Usage

        
 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.

        Example Usage

        
 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.

        Example Usage

        
 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.

        Example Usage

        
 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.

        Example Usage

        
 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.

        Example Usage

        
 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.

        Example Usage

        
 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.

        Example Usage

        
 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.

        Example Usage

        
 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.

        Example Usage

        
 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.

        Example Usage

        
 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.

        Example Usage

        
 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