Package io.gdcc.spi.core.loader

Class PluginLoader<T extends Plugin>

java.lang.Object
io.gdcc.spi.core.loader.PluginLoader<T>
Type Parameters:
T - the type of plugin to load, constrained to implement the Plugin interface
public class PluginLoader<T extends Plugin> extends Object
Loads plugins of a specified type from JAR files in a given directory using the Java ServiceLoader mechanism.

Each plugin must implement the Plugin interface and provide a non-null, non-blank identity via the Plugin.identity() method. Plugins are loaded from individual JAR files, each loaded in its own URLClassLoader, enabling isolated class loading for plugin dependencies.

This class supports custom ClassLoader hierarchies to accommodate complex deployment environments, and aggregates errors encountered during plugin discovery and loading into a single LoaderException if no plugins are successfully loaded.

It supports one-time classloading, but no reloading of changed JARs at runtime. An application restart is required to pick up changes to plugin JARs.

  • Constructor Details

    • PluginLoader

      public PluginLoader(Class<T> pluginClass)
      Constructs a new PluginLoader that will load plugins of the specified type T. The parent ClassLoader is set to the current thread's context ClassLoader, which allows plugins to access classes and resources on the core's classpath. It uses the system default configuration for plugin loading behaviors, see LoaderConfiguration.defaults().
      Parameters:
      pluginClass - the Class object representing the plugin type T to load

    • PluginLoader

      public PluginLoader(Class<T> pluginClass, ClassLoader parentClassLoader)
      Constructs a new PluginLoader that will load plugins of the specified type T. It uses the system default configuration for plugin loading behaviors, see LoaderConfiguration.defaults().
      Parameters:
      pluginClass - the Class object representing the plugin type T to load
      parentClassLoader - the ClassLoader to be used as the parent for class loading of plugins

    • PluginLoader

      public PluginLoader(Class<T> pluginClass, LoaderConfiguration configuration)
      Constructs a new PluginLoader that will load plugins of the specified type T. The parent ClassLoader is set to the current thread's context ClassLoader, which allows plugins to access classes and resources on the core's classpath.
      Parameters:
      pluginClass - the Class object representing the type of plugin T to load
      configuration - the LoaderConfiguration specifying custom plugin loading behaviors

    • PluginLoader

      public PluginLoader(Class<T> pluginClass, LoaderConfiguration configuration, ClassLoader parentClassLoader)
      Constructs a new instance of the PluginLoader, which is responsible for loading plugins of the specified type T.
      Parameters:
      pluginClass - the Class object representing the type of plugin T to load
      configuration - the LoaderConfiguration specifying custom plugin loading behaviors
      parentClassLoader - the ClassLoader to be used as the parent for loading plugin classes and resources

  • Method Details

    • load

      public List<PluginHandle<T>> load(Path pluginJarsLocation)

      Loads all plugins of type T from JAR files located in the specified directory. Each JAR file is loaded using a dedicated URLClassLoader, and plugins are discovered via the Java ServiceLoader mechanism (META-INF/services/package.plus.service.ClassName file).

      For each discovered plugin, its Plugin.identity() must be non-null and non-blank; otherwise, it is skipped and an error is recorded.

      Parameters:
      pluginJarsLocation - the directory containing JAR files to scan for plugins
      Returns:
      a list of PluginHandle, linking each plugin's metadata to the corresponding plugin instance
      Throws:
      LoaderException - if one or more errors occur during loading, if no plugins could be successfully loaded, or if there are any duplicates. Note: The exception may contain multiple causes, each associated with a specific file or failure point