net.opentsdb.utils

Class PluginLoader

java.lang.Object

net.opentsdb.utils.PluginLoader

public final class PluginLoader
extends Object

Super simple ServiceLoader based plugin framework for OpenTSDB that lets us add files or directories to the class path after startup and then search for a specific plugin type or any plugins that match a given class. This isn't meant to be a rich plugin manager, it only handles the basics of searching and instantiating a given class.

Before attempting any of the plugin loader calls, users should call one or more of the jar loader methods to append files to the class path that may have not been loaded on startup. This is particularly useful for plugins that have dependencies not included by OpenTSDB.

For example, a typical process may be:

• loadJARs(<plugin_path>) where <plugin_path> contains JARs of the plugins and their dependencies
• loadSpecificPlugin() or loadPlugins() to instantiate the proper plugin types

Plugin creation is pretty simple, just implement the abstract plugin class, create a Manifest file, add the "services" folder and plugin file and export a jar file.

Note: All plugins must have a parameterless constructor for the ServiceLoader to work. This means you can't have final class variables, but we'll make a promise to call an initialize() method with the proper parameters, such as configs or the TSDB object, immediately after loading a plugin and before trying to access any of its methods.

Note: All plugins must also implement a shutdown() method to clean up gracefully.

Since:

2.0

Constructor Summary

Constructors

Constructor and Description
PluginLoader()

Method Summary

Methods

Modifier and Type	Method and Description
static void	loadJAR(String jar) Attempts to load the given jar into the class path
static void	loadJARs(String directory) Recursively traverses a directory searching for files ending with .jar and loads them into the class path
static <T> List<T>	loadPlugins(Class<T> type) Searches the class path for implementations of the given type, returning a list of all plugins that were found
static <T> T	loadSpecificPlugin(String name, Class<T> type) Searches the class path for the specific plugin of a given type

Methods inherited from class java.lang.Object

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

Constructor Detail

PluginLoader

public PluginLoader()

Method Detail

loadSpecificPlugin

public static <T> T loadSpecificPlugin(String name,
                       Class<T> type)

Searches the class path for the specific plugin of a given type

Note: If you want to load JARs dynamically, you need to call loadJAR(java.lang.String) or loadJARs(java.lang.String) methods with the proper file or directory first, otherwise this will only search whatever was loaded on startup.

WARNING: If there are multiple versions of the request plugin in the class path, only one will be returned, so check the logs to see that the correct version was loaded.

Parameters:

name - The specific name of a plugin to search for, e.g. net.opentsdb.search.ElasticSearch

type - The class type to search for

Returns:

An instantiated object of the given type if found, null if the class could not be found

Throws:

ServiceConfigurationError - if the plugin cannot be instantiated

IllegalArgumentName - if the plugin name is null or empty

loadPlugins

public static <T> List<T> loadPlugins(Class<T> type)

Searches the class path for implementations of the given type, returning a list of all plugins that were found

Note: If you want to load JARs dynamically, you need to call loadJAR(java.lang.String) or loadJARs(java.lang.String) methods with the proper file or directory first, otherwise this will only search whatever was loaded on startup.

WARNING: If there are multiple versions of the request plugin in the class path, only one will be returned, so check the logs to see that the correct version was loaded.

Parameters:

type - The class type to search for

Returns:

An instantiated list of objects of the given type if found, null if no implementations of the type were found

Throws:

ServiceConfigurationError - if any of the plugins could not be instantiated

loadJAR

public static void loadJAR(String jar)
                    throws IOException,
                           SecurityException,
                           IllegalArgumentException,
                           NoSuchMethodException,
                           IllegalAccessException,
                           InvocationTargetException

Attempts to load the given jar into the class path

Parameters:

jar - Full path to a .jar file

Throws:

IOException - if the file does not exist or cannot be accessed

SecurityException - if there is a security manager present and the operation is denied

IllegalArgumentException - if the filename did not end with .jar

NoSuchMethodException - if there is an error with the class loader

IllegalAccessException - if a security manager is present and the operation was denied

InvocationTargetException - if there is an issue loading the jar

loadJARs

public static void loadJARs(String directory)
                     throws SecurityException,
                            IllegalArgumentException,
                            IOException,
                            NoSuchMethodException,
                            IllegalAccessException,
                            InvocationTargetException

Recursively traverses a directory searching for files ending with .jar and loads them into the class path

WARNING: This can be pretty slow if you have a directory with many sub-directories. Keep the directory structure shallow.

Parameters:

directory - The directory

Throws:

IOException - if the directory does not exist or cannot be accessed

SecurityException - if there is a security manager present and the operation is denied

IllegalArgumentException - if the path was not a directory

NoSuchMethodException - if there is an error with the class loader

IllegalAccessException - if a security manager is present and the operation was denied

InvocationTargetException - if there is an issue loading the jar