com.inet.plugin.ServerPluginManager

public class ServerPluginManager extends 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

Description

static enum

ServerPluginManager.PluginLoadFailCause

Possible cause why a plugin was not loaded.

static enum

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

Description

static final boolean

DEBUG

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

static final boolean

IS_SERVLET_API

signals if the servlet API is available
Constructor Summary

Constructors

Modifier

Constructor

Description

protected

ServerPluginManager()

Create a instance of ServerPluginManager.
Method Summary

Modifier and Type

Method

Description

boolean

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(@Nonnull Class<T> interfaceClass)

Get a new modifiable list of instances of the given extension type.

String[]

getAvailablePlugins()

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

String

getCorePluginId()

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

static @Nonnull String

getDiagnostic()

FOR INTERNAL USE ONLY Get additional diagnostic information for the case of fatal error:

static ServerPluginManager

getInstance()

Gets the current instance of the ServerPluginManager.

String[]

getLoadedPlugins()

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

getPluginDescription(String id)

FOR INTERNAL USE ONLY Get the description of a plugin or null

com.inet.plugin.fs.ResourceFile

getPluginDir()

Get the base plugin directory.

@Nonnull List<com.inet.plugin.fs.ResourceFile>

getPluginDirs()

Get the locations from which plugins are loaded.

com.inet.plugin.fs.ResourceFile

getPluginFile(String id, String path)

Returns a ResourceFile for a file which is contained in a plugin.

@Nullable PluginFilter

getPluginFilter()

Return a plugin filter which filter the available plugins

Object

getPluginLoadError(String id)

Get 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> T

getSingleInstanceByName(@Nonnull Class<T> interfaceClass, @Nullable String instanceKey, boolean useDefault)

Get a single instance of a certain type.

@Nonnull Properties

getStartProperties()

Get the start properties.

ServerPluginManager.ServerPluginManagerState

getState()

Get the current state of the manager

File

getTempDir()

FOR INTERNAL USE ONLY Get the temp directory and clear it from old files.

Throwable

getThrowable()

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

@Nonnull com.inet.plugin.fs.ResourceFile

getTranslationsDir()

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

init(@Nullable String corePluginId)

Deprecated.

boolean

isInitFinish()

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.

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

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.

<T> void

register(Class<T> interfaceClass, T instance)

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 plugins

void

setPluginFilter(PluginFilter filter)

Set a plugin filter which filter the available plugins

void

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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- 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 Details
- ServerPluginManager
  
  protected ServerPluginManager()
  
  Create a instance of ServerPluginManager.
  
  Since:
  
  inetcore 1.0
Method Details
- 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
- 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
  
  public <T> void register(Class<T> interfaceClass, T instance)
  
  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 be null
  
  instance - a instance which T implements or extends
  
  Throws:
  
  IllegalStateException - if the State of the ServerPluginManager is ServerPluginManager.ServerPluginManagerState.INIT
  
  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 <T> @Nonnull List<T> get(@Nonnull @Nonnull Class<T> interfaceClass)
  
  Get a new modifiable list of instances of the given extension type. The extensions need to be registered before with register(Class, Object)
  
  Type Parameters:
  
  T - a interface or a class (preferred abstract)
  
  Parameters:
  
  interfaceClass - a class of type T, can not be null
  
  Returns:
  
  a list of instances. can be empty but not null
  
  Throws:
  
  IllegalStateException - if the State of the ServerPluginManager is differ from ServerPluginManager.ServerPluginManagerState.INIT
  
  Since:
  
  inetcore 1.0
- getSingleInstance
  
  @Nonnull public <T> T getSingleInstance(Class<T> interfaceClass) throws IllegalStateException
  
  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 be null
  
  Returns:
  
  a single instance of type T
  
  Throws:
  
  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 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 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:
  
  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> T getOptionalInstance(Class<T> interfaceClass) throws IllegalStateException
  
  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 be null
  
  Returns:
  
  a optional instance of type T or null
  
  Throws:
  
  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
- addExtractedPlugin
  
  public boolean addExtractedPlugin(@Nonnull @Nonnull String className)
  Add an extracted plugin that can be load from system/base classloader. It is loaded with:
  Class.forName( className );
  The plugin must have an 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 public void init(@Nullable @Nullable com.inet.plugin.ServerPluginDescription core)
  
  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 is ServerPluginManager.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 is ServerPluginManager.ServerPluginManagerState.INIT
  
  Since:
  
  inetcore 24.4
- init
  
  @Deprecated public void init(@Nullable @Nullable String corePluginId)
  
  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 is ServerPluginManager.ServerPluginManagerState.INIT
  
  Since:
  
  inetcore 5.1
- getCorePluginId
  
  public 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(String corePluginId) throws IllegalStateException
  
  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
  
  public File 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
  
  public com.inet.plugin.fs.ResourceFile getPluginFile(String id, String path) throws 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. Note: you can not use it for directories!
  
  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:
  
  IOException - thrown if the ZIP or JAR cannot be accessed
  
  Since:
  
  inetcore 1.0
- isPluginLoaded
  
  public boolean isPluginLoaded(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
- 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 ID
  
  pluginRegisterSupplier - the subblier to return a PluginRegister instance, the run method will be called of.
  
  Since:
  
  inetcore 21.10
- getPluginLoadError
  
  public Object getPluginLoadError(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
- setPluginLoadError
  
  public void setPluginLoadError(String id, Throwable th)
  
  Set the cause because a plugin was not loaded.
  
  Parameters:
  
  id - the plugin ID
  
  th - the cause
  
  Since:
  
  23.4
- getLoadedPlugins
  
  public 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 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(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:
  
  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:
  
  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 @Nonnull 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 @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
  
  public void setPluginFilter(PluginFilter filter)
  
  Set a plugin filter which filter the available plugins
  
  Parameters:
  
  filter - the new filter
  
  Since:
  
  inetcore 2.0
- getPluginFilter
  
  @Nullable public @Nullable PluginFilter getPluginFilter()
  
  Return a plugin filter which filter the available plugins
  
  Returns:
  
  the new filter, null for no filter
  
  Since:
  
  inetcore 21.10
- setActived
  
  public void setActived(Map<String,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 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
- getPluginDescription
  
  public com.inet.plugin.ServerPluginDescription getPluginDescription(String id)
  
  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
  
  @Nonnull public @Nonnull 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:
  
  IllegalStateException - if ServerPluginManager's state is not PRE_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 plugin
  
  IllegalStateException - 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 plugin
  
  IllegalStateException - if call after init the plugin manager
  
  Since:
  
  20.4
- getDiagnostic
  
  @Nonnull public static @Nonnull String getDiagnostic()
  
  FOR INTERNAL USE ONLY Get additional diagnostic information for the case of fatal error:
  
  Returns:
  
  a string starting with newline
  
  Since:
  
  21.4

Class ServerPluginManager

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

DEBUG

IS_SERVLET_API

Constructor Details

ServerPluginManager

Method Details

getInstance

reset

register

get

getSingleInstance

getSingleInstanceByName

getOptionalInstance

addExtractedPlugin

init

init

init

getCorePluginId

setCorePluginId

getTempDir

readPluginsFromDirectory

loadDirectory

getPluginFile

isPluginLoaded

runIfPluginLoaded

getPluginLoadError

setPluginLoadError

getLoadedPlugins

getAvailablePlugins

setPluginDir

setPluginDir

getPluginDir

getPluginDirs

getTranslationsDir

setPluginFilter

getPluginFilter

setActived

getState

isInitFinish

waitOnInitState

getThrowable

getPluginDescription

getStartProperties

uninstall

findCoreServerPluginDescriptionWithoutLoadingForServerStart

loadCoreServerPluginDescriptionForServerStart

getDiagnostic