org.pfsw.plugin

Class PluginLoader<TInterface>

java.lang.Object

org.pfsw.plugin.PluginLoader<TInterface>

public abstract class PluginLoader<TInterface>
extends java.lang.Object

An abstract class that implements the generic logic to load a configured implementation class for a specific interface through different variants of loading mechanisms. The following list describes the order of mechanisms tried. The first that successfully creates an instance will end the process and return that instance.

1. Check if a configuration parameter for the implementation class is set. If that's the case, an instance of this class is created and returned.
2. Check if an configuration parameter for the alias of the implementation class is set. If that's the case, all plugin-registration implementations on the classpath will be checked for aliases and associated classes that implement the TInterface. The the class for the configured alias will be loaded and returned.
3. Finally the Java ServiceLoader mechanism will be used to find an implementation class for the TInterface.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PluginLoader(java.lang.Class<TInterface> interfaceClass, java.lang.String classNameConfigParamName, java.lang.String aliasConfigParamName)

Method Summary

Modifier and Type	Method and Description
protected ClassRegistry<TInterface>	autoLoadPlugins(java.lang.ClassLoader loader)
protected TInterface	createInstanceFromServiceDeclaration(java.lang.ClassLoader classLoader)
protected boolean	defaultToFirstEntry() The return value of this method defines if the first entry in the found plugins should be returned as default if no explicit alias name has been provided in the configuration settings.
protected java.lang.ClassLoader	determineClassLoader(java.lang.ClassLoader classLoader)
protected java.lang.String	getAliasConfigParamName()
ClassRegistry<TInterface>	getAllPluginsViaPluginRegistration() Returns all plugins that can be found via the PluginRegistration mechanism for the underlying interface definition.
ClassRegistry<TInterface>	getAllPluginsViaPluginRegistration(java.lang.ClassLoader loader) Returns all plugins that can be found via the PluginRegistration mechanism for the underlying interface definition using the given class loader as preferred class loader for the Java ServiceLoader lookup.
protected java.lang.String	getClassNameConfigParamName()
protected java.lang.Class<TInterface>	getInterfaceClass()
protected java.lang.String	getParameterNames()
protected TInterface	loadFirstFoundInstance(java.lang.ClassLoader classLoader) Returns the and instance of the first found class definition.
protected TInterface	loadInstance(java.lang.ClassLoader classLoader, java.lang.Class<TInterface> implClass) Returns the instance for the given class.
protected TInterface	loadInstance(java.lang.ClassLoader classLoader, java.lang.String className) Returns the instance for the given className.
protected TInterface	loadInstanceByAlias(java.lang.ClassLoader classLoader, java.lang.String aliasName) Returns the instance for the given alias.
protected TInterface	loadInstanceFromService(java.lang.ClassLoader classLoader) Returns the instance that is specified in the first META-INF/services/full-qualified-TInterface-name file on the classpath.
TInterface	loadPlugin(java.lang.ClassLoader classLoader, IConfigSettings config, boolean fallbackToServiceLoader) Returns the instance that is specified by class name configuration parameter or indirectly by the alias name optionally defined in the alias configuration parameter.
TInterface	loadPlugin(IConfigSettings config) Returns the instance that is specified by class name configuration parameter or indirectly by the alias name optionally defined in the alias configuration parameter.
protected PluginUtil	pluginUtil()

Methods inherited from class java.lang.Object

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

Constructor Detail

PluginLoader

protected PluginLoader(java.lang.Class<TInterface> interfaceClass,
                       java.lang.String classNameConfigParamName,
                       java.lang.String aliasConfigParamName)

Method Detail

loadPlugin

public TInterface loadPlugin(IConfigSettings config)
                      throws ConfigurationException

Returns the instance that is specified by class name configuration parameter or indirectly by the alias name optionally defined in the alias configuration parameter. This class must be available to the given class loader.

If the class configuration parameter is not specified and the alias names is also not available then the class will be looked-up using the Java service loader mechanism. In that case the first found implementation class for interface TInterface will be taken. Wherever a classloader is needed the current thread's context class loader will be used.

Parameters:

config - The configuration from which the parameters for class name or alias name will be taken (must not be null).

Returns:

The instance of the configured TInterface service.

Throws:

ConfigurationException - If no implementation class was configured or it cannot be instantiated.

loadPlugin

public TInterface loadPlugin(java.lang.ClassLoader classLoader,
                             IConfigSettings config,
                             boolean fallbackToServiceLoader)
                      throws ConfigurationException

Returns the instance that is specified by class name configuration parameter or indirectly by the alias name optionally defined in the alias configuration parameter. This class must be available to the given class loader.

If the class configuration parameter is not specified and the alias names is also not available then either a ConfigurationException gets thrown (fallbackToServiceLoader=false) or the class will be looked-up using the service loader mechanism (fallbackToServiceLoader=true). In that case the first found implementation class for interface TInterface will be taken.

Parameters:

classLoader - An optional class loader. If null the current threads context classloader will be used.

config - The configuration from which the parameters for class name or alias name will be taken (must not be null).

fallbackToServiceLoader - Definition whether or not finally the Java ServiceLoader mechanism should be tried.

Returns:

The instance of the configured TInterface service.

Throws:

ConfigurationException - If no implementation class was configured or it cannot be instantiated.

getAllPluginsViaPluginRegistration

public ClassRegistry<TInterface> getAllPluginsViaPluginRegistration()

Returns all plugins that can be found via the PluginRegistration mechanism for the underlying interface definition.

getAllPluginsViaPluginRegistration

public ClassRegistry<TInterface> getAllPluginsViaPluginRegistration(java.lang.ClassLoader loader)

Returns all plugins that can be found via the PluginRegistration mechanism for the underlying interface definition using the given class loader as preferred class loader for the Java ServiceLoader lookup.

Parameters:

loader - The preferred class loader (may be null).

loadInstanceFromService

protected TInterface loadInstanceFromService(java.lang.ClassLoader classLoader)
                                      throws ConfigurationException

Returns the instance that is specified in the first META-INF/services/full-qualified-TInterface-name file on the classpath.

Parameters:

classLoader - An optional class loader to lookup the service implementors (may be null).

Returns:

The instance of the configured TInterface service.

Throws:

ConfigurationException - If no implementation class was configured or it cannot be instantiated.

loadInstance

protected TInterface loadInstance(java.lang.ClassLoader classLoader,
                                  java.lang.String className)
                           throws ConfigurationException

Returns the instance for the given className. It uses the given classLoader to find the class.

Parameters:

classLoader - The class loader to use for loading the class. If null the class loader of this class will be used.

className - The name of the class that implements interface TInterface (must not be null).

Returns:

The instance of the TInterface implementing class specified by the className.

Throws:

ConfigurationException - If the class cannot be loaded or instantiated.

loadInstanceByAlias

protected TInterface loadInstanceByAlias(java.lang.ClassLoader classLoader,
                                         java.lang.String aliasName)

Returns the instance for the given alias. It uses the given classLoader to automatically load all alias to implementation class mappings.

Parameters:

classLoader - The class loader to use for loading the class mapping. If null the context classloader or the class loader of this class will be used.

aliasName - The name of the alias that is associated to a class that implements interface TInterface (must not be null).

Returns:

The instance of the TInterface implementing class specified by the aliasName or null if not found.

loadFirstFoundInstance

protected TInterface loadFirstFoundInstance(java.lang.ClassLoader classLoader)

Returns the and instance of the first found class definition. It uses the given classLoader to automatically load all implementation class mappings via the PluginRegistration mechanism.

Parameters:

classLoader - The class loader to use for loading the class mapping. If null the context classloader or the class loader of this class will be used.

Returns:

The instance of the TInterface implementing class specified by the aliasName or null if not found.

loadInstance

protected TInterface loadInstance(java.lang.ClassLoader classLoader,
                                  java.lang.Class<TInterface> implClass)
                           throws ConfigurationException

Returns the instance for the given class.

Parameters:

classLoader - An optional classloader to be used for looking up the interface implementations.

implClass - The class to instantiate. If null the service loader mechanism will be used (looking for file META-INF/services/TInterface).

Returns:

The instance of the TInterface specified by given class.

Throws:

ConfigurationException - If the class cannot be instantiated.

createInstanceFromServiceDeclaration

protected TInterface createInstanceFromServiceDeclaration(java.lang.ClassLoader classLoader)

autoLoadPlugins

protected ClassRegistry<TInterface> autoLoadPlugins(java.lang.ClassLoader loader)

determineClassLoader

protected java.lang.ClassLoader determineClassLoader(java.lang.ClassLoader classLoader)

getParameterNames

protected java.lang.String getParameterNames()

defaultToFirstEntry

protected boolean defaultToFirstEntry()

The return value of this method defines if the first entry in the found plugins should be returned as default if no explicit alias name has been provided in the configuration settings.

Here it returns always false - so no default will be provided.
Subclasses may override this method to alter the behavior.

getInterfaceClass

protected java.lang.Class<TInterface> getInterfaceClass()

getClassNameConfigParamName

protected java.lang.String getClassNameConfigParamName()

getAliasConfigParamName

protected java.lang.String getAliasConfigParamName()

pluginUtil

protected PluginUtil pluginUtil()