Package com.inet.plugin
Class ServerPluginManager
java.lang.Object
com.inet.plugin.ServerPluginManager
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
Modifier and TypeClassDescriptionstatic enum
Possible cause why a plugin was not loaded.static enum
The state the plugin manager is in: whether before initialization, currently registering plugins, initialized, or resetting -
Field Summary
Modifier and TypeFieldDescriptionstatic final boolean
Signals if we run a debug session in an IDE like Eclipse.static final boolean
signals if the servlet API is available -
Constructor Summary
ModifierConstructorDescriptionprotected
Create a instance of ServerPluginManager. -
Method Summary
Modifier and TypeMethodDescriptionboolean
addExtractedPlugin
(@Nonnull String className) Add an extracted plugin that can be load from system/base classloader.protected @Nullable com.inet.plugin.ServerPluginDescription
findCoreServerPluginDescriptionWithoutLoadingForServerStart
(@Nullable String coreID, @Nonnull com.inet.logging.Logger logger) FOR INTERNAL USE ONLY Get the core server plugin description without loading for the testing framework.<T> @Nonnull List<T>
Get a new modifiable list of instances of the given extension type.String[]
Get the list of all available plugins in the plugin directory.Returns the id of the product core plugin that was provided to initialize the ServerPluginManager.static @Nonnull String
FOR INTERNAL USE ONLY Get additional diagnostic information for the case of fatal error:static ServerPluginManager
Gets the current instance of the ServerPluginManager.String[]
Get the list of all loaded/running plugins.<T> T
getOptionalInstance
(Class<T> interfaceClass) Get a optional instance of a specific type.com.inet.plugin.ServerPluginDescription
FOR INTERNAL USE ONLY Get the description of a plugin or nullcom.inet.plugin.fs.ResourceFile
Get the base plugin directory.@Nonnull List<com.inet.plugin.fs.ResourceFile>
Get the locations from which plugins are loaded.com.inet.plugin.fs.ResourceFile
getPluginFile
(String id, String path) Returns aResourceFile
for a file which is contained in a plugin.@Nullable PluginFilter
Return a plugin filter which filter the available pluginsGet the cause because a plugin was not loaded.<T> T
getSingleInstance
(Class<T> interfaceClass) Get a single instance of a specific type.<T extends NamedExtension>
TgetSingleInstanceByName
(@Nonnull Class<T> interfaceClass, @Nullable String instanceKey, boolean useDefault) Get a single instance of a certain type.@Nonnull Properties
Get the start properties.getState()
Get the current state of the managerFOR INTERNAL USE ONLY Get the temp directory and clear it from old files.Get a throwable that occur on init of the plugin manager.@Nonnull com.inet.plugin.fs.ResourceFile
Get the directory where additional translations can be saved.void
init
(@Nullable com.inet.plugin.ServerPluginDescription core) Deprecated.void
init
(@Nullable com.inet.plugin.ServerPluginDescription... plugins) FOR INTERNAL USE ONLY Initialize the ServerPluginManager and start the live cycle of the plugins.void
Deprecated.boolean
If the init phase is complete.boolean
isPluginLoaded
(String id) Check if a plugin was loaded and can used in other plugins for access to API of optional dependencies.@Nullable com.inet.plugin.ServerPluginDescription
loadCoreServerPluginDescriptionForServerStart
(@Nullable String coreID) Get the core server plugin for recovery and process starter.loadDirectory
(com.inet.plugin.fs.ResourceFile pluginsDir) FOR INTERNAL USE ONLY Durchgang #1 : plugins erst mal initial einlesenreadPluginsFromDirectory
(com.inet.plugin.fs.ResourceFile[] archives) FOR INTERNAL USE ONLY Extrahiert die Plugin-Archive und erzeugt die Plugin-Beschreibungen.<T> void
Register a instance as extension in the ServerPluginManager.void
reset()
FOR INTERNAL USE ONLY Reset the ServerPluginManager after a server stop.void
runIfPluginLoaded
(String id, Supplier<com.inet.plugin.Executable> pluginRegisterSupplier) Runs the plugin register supplier when the plugin with the given id is loaded
and the caller was load from the DependencyClassLoader.
This code can be used in the register phase of a plugin to ensure that code of
optional plugins is only used executed, if available.void
setActived
(Map<String, Boolean> activated) Set the activated plugins.void
setCorePluginId
(String corePluginId) Set the name of the core plugin id.void
setPluginDir
(com.inet.plugin.fs.ResourceFile pluginDir) Set the relative or absolute plugin directory which is to be searched for plugins.void
setPluginDir
(String pluginDir) Set the relative or absolute path of plugin directory which is to be searched for pluginsvoid
setPluginFilter
(PluginFilter filter) Set a plugin filter which filter the available pluginsvoid
setPluginLoadError
(String id, Throwable th) Set the cause because a plugin was not loaded.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 Details
-
DEBUG
public static final boolean DEBUGSignals if we run a debug session in an IDE like Eclipse. -
IS_SERVLET_API
public static final boolean IS_SERVLET_APIsignals if the servlet API is available
-
-
Constructor Details
-
ServerPluginManager
protected ServerPluginManager()Create a instance of ServerPluginManager.- Since:
- inetcore 1.0
-
-
Method Details
-
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
-
reset
public void reset()FOR INTERNAL USE ONLY Reset the ServerPluginManager after a server stop. All loaded plugins are reset.- Since:
- inetcore 1.0
-
register
Register a instance as extension in the ServerPluginManager.- Type Parameters:
T
- a interface or a class (preferred abstract)- Parameters:
interfaceClass
- a class of type T, can not benull
instance
- a instance which T implements or extends- Throws:
IllegalStateException
- if the State of the ServerPluginManager isServerPluginManager.ServerPluginManagerState.INIT
IllegalArgumentException
- is thrown if the interfaceClasse implementsNamedExtension
and there already is an extension of the same name registered- Since:
- inetcore 1.0
-
get
Get a new modifiable list of instances of the given extension type. The extensions need to be registered before withregister(Class, Object)
- Type Parameters:
T
- a interface or a class (preferred abstract)- Parameters:
interfaceClass
- a class of type T, can not benull
- Returns:
- a list of instances. can be empty but not
null
- Throws:
IllegalStateException
- if the State of the ServerPluginManager is differ fromServerPluginManager.ServerPluginManagerState.INIT
- Since:
- inetcore 1.0
-
getSingleInstance
Get a single instance of a specific type.- Type Parameters:
T
- a interface or a class (preferred abstract)- Parameters:
interfaceClass
- a class of type T, can not benull
- Returns:
- a single instance of type T
- Throws:
IllegalStateException
- if the State of the ServerPluginManager is differ fromServerPluginManager.ServerPluginManagerState.INIT
or no instance or more as one instance of the needed type is registered- Since:
- inetcore 1.0
-
getSingleInstanceByName
@Nonnull public <T extends NamedExtension> T getSingleInstanceByName(@Nonnull @Nonnull Class<T> interfaceClass, @Nullable @Nullable String instanceKey, boolean useDefault) throws 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.- Type Parameters:
T
- a interface or a class (preferably abstract)- Parameters:
interfaceClass
- a class of type T, can not benull
instanceKey
- the name of the instance to be selected, ifnull
the default (aka. first instance) will be returneduseDefault
- iftrue
a fall back to the default instance is allowed, in case offalse
the user requires a certain instance. If no such instance is registered aIllegalStateException
will be thrown- Returns:
- a single instance of type T
- Throws:
IllegalStateException
- if the State of the ServerPluginManager is notServerPluginManager.ServerPluginManagerState.INIT
or if the requested instance/default could not be found- Since:
- inetcore 3.0
-
getOptionalInstance
Get a optional instance of a specific type.- Type Parameters:
T
- a interface or a class (preferred abstract)- Parameters:
interfaceClass
- a class of type T, can not benull
- Returns:
- a optional instance of type T or null
- Throws:
IllegalStateException
- if the state of ServerPluginManager is not eitherServerPluginManager.ServerPluginManagerState.INIT
orServerPluginManager.ServerPluginManagerState.RESET
or more than one instance of the needed type is registered- Since:
- inetcore 2.0
-
addExtractedPlugin
Add an extracted plugin that can be load from system/base classloader. It is loaded with:Class.forName( className );
PluginInfo
annotation as replacement for the plugin.properties. This method must be called before the initialize phase of the manager. The register and and init phase of the plugin will be invoked and own extensions can be registered. This method is not thread safe.- Parameters:
className
- the class name of the plugin- Returns:
- true, if the plugin was added; false, if any error occurred, see the log for details
- Since:
- 23.10
-
init
Deprecated.FOR INTERNAL USE ONLY Initialize the ServerPluginManager and start the live cycle of the plugins. there is no check.- Parameters:
core
- description of an optional core plugin- Throws:
IllegalStateException
- if the State of the ServerPluginManager isServerPluginManager.ServerPluginManagerState.INIT
- Since:
- inetcore 3.1
-
init
public void init(@Nullable @Nullable com.inet.plugin.ServerPluginDescription... plugins) FOR INTERNAL USE ONLY Initialize the ServerPluginManager and start the live cycle of the plugins. there is no check.- Parameters:
plugins
- optional descriptions of plugins, the first is used as core plugin- Throws:
IllegalStateException
- if the State of the ServerPluginManager isServerPluginManager.ServerPluginManagerState.INIT
- Since:
- inetcore 24.4
-
init
Deprecated.FOR INTERNAL USE ONLY Initialize the ServerPluginManager and start the live cycle of the plugins. there is no check.- Parameters:
corePluginId
- the ID of an optional core plugin- Throws:
IllegalStateException
- if the State of the ServerPluginManager isServerPluginManager.ServerPluginManagerState.INIT
- Since:
- inetcore 5.1
-
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
Set the name of the core plugin id. This can be set only once.- Parameters:
corePluginId
- the new ID- Throws:
IllegalStateException
- if the state is already init- Since:
- inetcore 5.1
-
getTempDir
FOR INTERNAL USE ONLY Get the temp directory and clear it from old files.- Returns:
- the directory
-
readPluginsFromDirectory
protected Map<String,com.inet.plugin.ServerPluginDescription> readPluginsFromDirectory(com.inet.plugin.fs.ResourceFile[] archives) FOR INTERNAL USE ONLY Extrahiert die Plugin-Archive und erzeugt die Plugin-Beschreibungen.- Parameters:
archives
- eine Liste mit den gefundenen Plugin-Archiven- Returns:
- Map mit Plugin-ID und Plugin-Beschreibung aller gefundenen Plugins
-
loadDirectory
protected Map<String,com.inet.plugin.ServerPluginDescription> loadDirectory(com.inet.plugin.fs.ResourceFile pluginsDir) FOR INTERNAL USE ONLY Durchgang #1 : plugins erst mal initial einlesen- Parameters:
pluginsDir
- Verzeichnis der Plugins- Returns:
- eine Map mit allen gefundenen Plugins, Key ist deren ID, nie
null
-
getPluginFile
Returns aResourceFile
for a file which is contained in a plugin. This may cover files in the jar files of a plugin as well. Note: you can not use it for directories!- Parameters:
id
- the ID of the plugin to get a file ofpath
- 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:
IOException
- thrown if the ZIP or JAR cannot be accessed- Since:
- inetcore 1.0
-
isPluginLoaded
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
-
runIfPluginLoaded
public void runIfPluginLoaded(String id, Supplier<com.inet.plugin.Executable> pluginRegisterSupplier) Runs the plugin register supplier when the plugin with the given id is loaded
and the caller was load from the DependencyClassLoader.
This code can be used in the register phase of a plugin to ensure that code of
optional plugins is only used executed, if available. It ensures the decoupling
of class loading.spm.runIfPluginLoaded( "reporting", () -> new Executable() { public void execute() { ... } } );
- Parameters:
id
- the plugin IDpluginRegisterSupplier
- the subblier to return a PluginRegister instance, the run method will be called of.- Since:
- inetcore 21.10
-
getPluginLoadError
Get the cause because a plugin was not loaded.- Parameters:
id
- the plugin ID- Returns:
- null, PluginLoadFailCause or a Throwbale
- Since:
- inetcore 2.2
-
setPluginLoadError
Set the cause because a plugin was not loaded.- Parameters:
id
- the plugin IDth
- the cause- Since:
- 23.4
-
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:
-
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
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 benull
.- Throws:
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 benull
.- Throws:
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
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 @Nonnull 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
Set a plugin filter which filter the available plugins- Parameters:
filter
- the new filter- Since:
- inetcore 2.0
-
getPluginFilter
Return a plugin filter which filter the available plugins- Returns:
- the new filter, null for no filter
- Since:
- inetcore 21.10
-
setActived
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
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
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
-
getPluginDescription
FOR INTERNAL USE ONLY Get the description of a plugin or null- Parameters:
id
- of the plugin- Returns:
- description of the plugin or null
- Since:
- inetcore 1.1
-
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:
IllegalStateException
- if ServerPluginManager's state is notPRE_INIT
.- Since:
- inetcore 2.2
-
findCoreServerPluginDescriptionWithoutLoadingForServerStart
@Nullable protected @Nullable com.inet.plugin.ServerPluginDescription findCoreServerPluginDescriptionWithoutLoadingForServerStart(@Nullable @Nullable String coreID, @Nonnull @Nonnull com.inet.logging.Logger logger) throws Exception FOR INTERNAL USE ONLY Get the core server plugin description without loading for the testing framework.- Parameters:
coreID
- optional/possible ID of a core plugin. This is only a hint.logger
- the logger- Returns:
- the plugin or null if not found.
- Throws:
Exception
- if any error occur on loading the pluginIllegalStateException
- if call after init the plugin manager- Since:
- 20.4
-
loadCoreServerPluginDescriptionForServerStart
@Nullable public @Nullable com.inet.plugin.ServerPluginDescription loadCoreServerPluginDescriptionForServerStart(@Nullable @Nullable String coreID) throws 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:
Exception
- if any error occur on loading the pluginIllegalStateException
- if call after init the plugin manager- Since:
- 20.4
-
getDiagnostic
FOR INTERNAL USE ONLY Get additional diagnostic information for the case of fatal error:- Returns:
- a string starting with newline
- Since:
- 21.4
-