com.inet.plugin

Class ServerPluginManager

java.lang.Object

com.inet.plugin.ServerPluginManager

public class ServerPluginManager
extends java.lang.Object

The ServerPluginManager is the central point in the server for the plugin framework. It detects the installed plugins and initializes them. Additionally, there are methods for registering and querying extensions.

Since:

inetcore 1.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ServerPluginManager.PluginLoadFailCause Possible cause why a plugin was not loaded.
static class	ServerPluginManager.ServerPluginManagerState The state the plugin manager is in: whether before initialization, currently registering plugins, initialized, or resetting

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	DEBUG Signals if we run a debug session in an IDE like Eclipse.
static boolean	IS_SERVLET_API signals if the servlet API is available

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ServerPluginManager() Create a instance of ServerPluginManager.

Method Summary

Modifier and Type	Method and Description
java.util.List<T>	get(java.lang.Class<T> interfaceClass) Get a list of instances of the given extension type.
java.lang.String[]	getAvailablePlugins() Get the list of all available plugins in the plugin directory.
java.lang.String	getCorePluginId() Returns the id of the product core plugin that was provided to initialize the ServerPluginManager.
com.inet.plugin.ServerPluginDescription	getCoreServerPluginDescription(java.lang.String coreID) Get the core server plugin for recovery and process starter.
static ServerPluginManager	getInstance() Gets the current instance of the ServerPluginManager.
java.lang.String[]	getLoadedPlugins() Get the list of all loaded/running plugins.
T	getOptionalInstance(java.lang.Class<T> interfaceClass) Get a optional instance of a specific type.
com.inet.plugin.fs.ResourceFile	getPluginDir() Get the base plugin directory.
java.util.List<com.inet.plugin.fs.ResourceFile>	getPluginDirs() Get the locations from which plugins are loaded.
com.inet.plugin.fs.ResourceFile	getPluginFile(java.lang.String id, java.lang.String path) Returns a ResourceFile for a file which is contained in a plugin.
java.lang.Object	getPluginLoadError(java.lang.String id) Get the cause because a plugin was not loaded.
T	getSingleInstance(java.lang.Class<T> interfaceClass) Get a single instance of a specific type.
T	getSingleInstanceByName(java.lang.Class<T> interfaceClass, java.lang.String instanceKey, boolean useDefault) Get a single instance of a certain type.
java.util.Properties	getStartProperties() Get the start properties.
ServerPluginManager.ServerPluginManagerState	getState() Get the current state of the manager
java.lang.Throwable	getThrowable() Get a throwable that occur on init of the plugin manager.
com.inet.plugin.fs.ResourceFile	getTranslationsDir() Get the directory where additional translations can be saved.
boolean	isInitFinish() If the init phase is complete.
boolean	isPluginLoaded(java.lang.String id) Check if a plugin was loaded and can used in other plugins for access to API of optional dependencies.
void	register(java.lang.Class<T> interfaceClass, T instance) Register a instance as extension in the ServerPluginManager.
void	setActived(java.util.Map<java.lang.String,java.lang.Boolean> activated) Set the activated plugins.
void	setCorePluginId(java.lang.String corePluginId) Set the name of the core plugin id.
void	setPluginDir(java.lang.String pluginDir) Set the relative or absolute path of plugin directory which is to be searched for plugins
void	setPluginDir(com.inet.plugin.fs.ResourceFile pluginDir) Set the relative or absolute plugin directory which is to be searched for plugins.
void	setPluginFilter(PluginFilter filter) Set a plugin filter which filter the available plugins
void	uninstall(com.inet.plugin.ServerPluginDescription core, boolean isFullUninstall) Executes uninstall tasks of available plugins.
void	waitOnInitState(int seconds) Wait the given count that the plugin manager will receive the state init.

Field Detail

DEBUG

public static final boolean DEBUG

Signals if we run a debug session in an IDE like Eclipse.

IS_SERVLET_API

public static final boolean IS_SERVLET_API

signals if the servlet API is available

Constructor Detail

ServerPluginManager

protected ServerPluginManager()

Create a instance of ServerPluginManager.

Since:

inetcore 1.0

Method Detail

getInstance

public static ServerPluginManager getInstance()

Gets the current instance of the ServerPluginManager. If one does not exist then it will be created.

Returns:

Singleton instance of the manager

Since:

inetcore 1.0

register

public void register(java.lang.Class<T> interfaceClass,
                     T instance)

Register a instance as extension in the ServerPluginManager.

Parameters:

interfaceClass - a class of type T, can not be null

instance - a instance which T implements or extends

Throws:

java.lang.IllegalStateException - if the State of the ServerPluginManager is ServerPluginManager.ServerPluginManagerState.INIT

java.lang.IllegalArgumentException - is thrown if the interfaceClasse implements NamedExtension and there already is an extension of the same name registered

Since:

inetcore 1.0

get

@Nonnull
public java.util.List<T> get(@Nonnull
                                       java.lang.Class<T> interfaceClass)

Get a list of instances of the given extension type. The extensions need to be registered before with register(Class, Object)

Parameters:

interfaceClass - a class of type T, can not be null

Returns:

a list of instances. can be empty but not null

Throws:

java.lang.IllegalStateException - if the State of the ServerPluginManager is differ from ServerPluginManager.ServerPluginManagerState.INIT

Since:

inetcore 1.0

getSingleInstance

@Nonnull
public T getSingleInstance(java.lang.Class<T> interfaceClass)
                              throws java.lang.IllegalStateException

Get a single instance of a specific type.

Parameters:

interfaceClass - a class of type T, can not be null

Returns:

a single instance of type T

Throws:

java.lang.IllegalStateException - if the State of the ServerPluginManager is differ from ServerPluginManager.ServerPluginManagerState.INIT or no instance or more as one instance of the needed type is registered

Since:

inetcore 1.0

getSingleInstanceByName

@Nonnull
public T getSingleInstanceByName(@Nonnull
                                           java.lang.Class<T> interfaceClass,
                                           @Nullable
                                           java.lang.String instanceKey,
                                           boolean useDefault)
                                    throws java.lang.IllegalStateException

Get a single instance of a certain type. The instance can be selected using it's extension name. If no name is set or there is no instance of such name, the default instance may be returned. The default is defined as the first instance that was registered for the a type.

Parameters:

interfaceClass - a class of type T, can not be null

instanceKey - the name of the instance to be selected, if null the default (aka. first instance) will be returned

useDefault - if true a fall back to the default instance is allowed, in case of false the user requires a certain instance. If no such instance is registered a IllegalStateException will be thrown

Returns:

a single instance of type T

Throws:

java.lang.IllegalStateException - if the State of the ServerPluginManager is not ServerPluginManager.ServerPluginManagerState.INIT or if the requested instance/default could not be found

Since:

inetcore 3.0

getOptionalInstance

@Nullable
public T getOptionalInstance(java.lang.Class<T> interfaceClass)
                                 throws java.lang.IllegalStateException

Get a optional instance of a specific type.

Parameters:

interfaceClass - a class of type T, can not be null

Returns:

a optional instance of type T or null

Throws:

java.lang.IllegalStateException - if the state of ServerPluginManager is not either ServerPluginManager.ServerPluginManagerState.INIT or ServerPluginManager.ServerPluginManagerState.RESET or more than one instance of the needed type is registered

Since:

inetcore 2.0

getCorePluginId

public java.lang.String getCorePluginId()

Returns the id of the product core plugin that was provided to initialize the ServerPluginManager.

Returns:

the id of the plugin. Can be null if not core plugin was provided.

Since:

inetcore 1.1

setCorePluginId

public void setCorePluginId(java.lang.String corePluginId)
                     throws java.lang.IllegalStateException

Set the name of the core plugin id. This can be set only once.

Parameters:

corePluginId - the new ID

Throws:

java.lang.IllegalStateException - if the state is already init

Since:

inetcore 5.1

getPluginFile

public com.inet.plugin.fs.ResourceFile getPluginFile(java.lang.String id,
                                                     java.lang.String path)
                                              throws java.io.IOException

Returns a ResourceFile for a file which is contained in a plugin. This may cover files in the jar files of a plugin as well

Parameters:

id - the ID of the plugin to get a file of

path - the path into the plugin ZIP file or one of the plugin JAR files

Returns:

the requested file, may be null if there is no such plugin or file

Throws:

java.io.IOException - thrown if the ZIP or JAR cannot be accessed

Since:

inetcore 1.0

isPluginLoaded

public boolean isPluginLoaded(java.lang.String id)

Check if a plugin was loaded and can used in other plugins for access to API of optional dependencies. Do not access to the API of an optional plugin in an IF block or inside a lambda expression. Use an extra class or anonymous class to decouple class loading. For example:

 if( spm.isPluginLoaded( "reporting" ) ) {
     new Runnable() { // anonymous class to decouple class loading
         public void run() {
             ...
         }
     }.run();
 }
 

Parameters:

id - the plugin ID

Returns:

true, if the plugin is available and loaded.

Since:

inetcore 1.1

getPluginLoadError

public java.lang.Object getPluginLoadError(java.lang.String id)

Get the cause because a plugin was not loaded.

Parameters:

id - the plugin ID

Returns:

null, PluginLoadFailCause or a Throwbale

Since:

inetcore 2.2

getLoadedPlugins

public java.lang.String[] getLoadedPlugins()

Get the list of all loaded/running plugins. This method can be called in the register and init phase (and later). In the pre_init phase it will return only an empty result.

Returns:

a list of IDs from loaded plugins

Since:

inetcore 1.0

See Also:

isPluginLoaded(String)

getAvailablePlugins

public java.lang.String[] getAvailablePlugins()

Get the list of all available plugins in the plugin directory.

Returns:

a list of IDs from all plugins

Since:

inetcore 1.0

setPluginDir

public void setPluginDir(java.lang.String pluginDir)

Set the relative or absolute path of plugin directory which is to be searched for plugins

Parameters:

pluginDir - the path of the plugin directory, can not be null.

Throws:

java.lang.IllegalStateException - if the state is already init

Since:

inetcore 1.0

setPluginDir

public void setPluginDir(com.inet.plugin.fs.ResourceFile pluginDir)

Set the relative or absolute plugin directory which is to be searched for plugins. Can be set only once.

Parameters:

pluginDir - the path of the plugin directory, can not be null.

Throws:

java.lang.IllegalStateException - if the state is already init

Since:

inetcore 1.0

getPluginDir

public com.inet.plugin.fs.ResourceFile getPluginDir()

Get the base plugin directory. If not set then it returns the "plugins" path relative to the application base.

Returns:

the plugin dir

Since:

inetcore 5.2

getPluginDirs

@Nonnull
public java.util.List<com.inet.plugin.fs.ResourceFile> getPluginDirs()

Get the locations from which plugins are loaded. The list returns at minimum one element. If the core plugin is set and this is a file persistence there can be an additional directory.

Returns:

the directories

Since:

inetcore 5.2

getTranslationsDir

@Nonnull
public com.inet.plugin.fs.ResourceFile getTranslationsDir()

Get the directory where additional translations can be saved.

Returns:

the custom translation directory

Since:

inetcore 5.2

setPluginFilter

public void setPluginFilter(PluginFilter filter)

Set a plugin filter which filter the available plugins

Parameters:

filter - the new filter

Since:

inetcore 2.0

setActived

public void setActived(java.util.Map<java.lang.String,java.lang.Boolean> activated)

Set the activated plugins. All plugins not in the map use the default behavior of the plugin. This replace the settings in the configuration manager.

Parameters:

activated - a map of plugin id to a boolean flag

Since:

inetcore 5.0

getState

public ServerPluginManager.ServerPluginManagerState getState()

Get the current state of the manager

Returns:

the state

Since:

inetcore 1.0

isInitFinish

public boolean isInitFinish()

If the init phase is complete.

Returns:

return true

Since:

20.4

waitOnInitState

public void waitOnInitState(int seconds)

Wait the given count that the plugin manager will receive the state init. This can only called from asynchrony background threads.

Parameters:

seconds - time in seconds to wait

Since:

inetcore 5.1

getThrowable

public java.lang.Throwable getThrowable()

Get a throwable that occur on init of the plugin manager.

Returns:

a throwable or null if no fatal error occur.

Since:

inetcore 2.0

getStartProperties

@Nonnull
public java.util.Properties getStartProperties()

Get the start properties. A plugin can vary its behavier depending on this properties.

Returns:

the start properties.

Since:

inetcore 2.0

uninstall

public void uninstall(com.inet.plugin.ServerPluginDescription core,
                      boolean isFullUninstall)

Executes uninstall tasks of available plugins. In case of problems with loading plugin, its task execution will be skipped and process will continue.

Parameters:

core - description of a optional core plugin (may be null).

isFullUninstall - whether a full uninstall must be performed.

Throws:

java.lang.IllegalStateException - if ServerPluginManager's state is not PRE_INIT.

Since:

inetcore 2.2

getCoreServerPluginDescription

@Nullable
public com.inet.plugin.ServerPluginDescription getCoreServerPluginDescription(@Nullable
                                                                                         java.lang.String coreID)
                                                                                  throws java.lang.Exception

Get the core server plugin for recovery and process starter. If find then this plugin is used for the launcher.

Parameters:

coreID - optional/possible ID of a core plugin. This is only a hint.

Returns:

the plugin or null if not found.

Throws:

java.lang.Exception - if any error occur on loading the plugin

java.lang.IllegalStateException - if call after init the plugin manager

Since:

20.4