Package com.inet.plugin

Class ServerPluginManager

java.lang.Object
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(String className)
    Add an extracted plugin that can be load from system/base classloader.
    protected com.inet.plugin.ServerPluginDescription
    findCoreServerPluginDescriptionWithoutLoadingForServerStart(String coreID, com.inet.logging.Logger logger)
    FOR INTERNAL USE ONLY Get the core server plugin description without loading for the testing framework.
    <T> List<T>
    get(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 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.
    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.
    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(Class<T> interfaceClass, String instanceKey, boolean useDefault)
    Get a single instance of a certain type.
    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.
    com.inet.plugin.fs.ResourceFile
    getTranslationsDir()
    Get the directory where additional translations can be saved.
    void
    init(com.inet.plugin.ServerPluginDescription core)
    Deprecated.
    void
    init(com.inet.plugin.ServerPluginDescription... plugins)
    FOR INTERNAL USE ONLY Initialize the ServerPluginManager and start the live cycle of the plugins.
    void
    init(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.
    com.inet.plugin.ServerPluginDescription
    loadCoreServerPluginDescriptionForServerStart(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> List<T> get(@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 Class<T> interfaceClass, @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 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 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 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 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:

    • 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 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

    • getPluginFilter

      @Nullable public 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 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 com.inet.plugin.ServerPluginDescription findCoreServerPluginDescriptionWithoutLoadingForServerStart(@Nullable String coreID, @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 com.inet.plugin.ServerPluginDescription loadCoreServerPluginDescriptionForServerStart(@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 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