Package com.inet.plugin

Class 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

    • Field Summary

      Fields 
      Modifier and Type Field 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 Description
      protected ServerPluginManager()
      Create a instance of ServerPluginManager.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean addExtractedPlugin​(java.lang.String className)
      Add an extracted plugin that can be load from system/base classloader.
      protected com.inet.plugin.ServerPluginDescription findCoreServerPluginDescriptionWithoutLoadingForServerStart​(java.lang.String coreID, com.inet.logging.Logger logger)
      FOR INTERNAL USE ONLY Get the core server plugin description without loading for the testing framework.
      <T> 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.
      static java.lang.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.
      java.lang.String[] getLoadedPlugins()
      Get the list of all loaded/running plugins.
      <T> T getOptionalInstance​(java.lang.Class<T> interfaceClass)
      Get a optional instance of a specific type.
      com.inet.plugin.ServerPluginDescription getPluginDescription​(java.lang.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.
      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.
      PluginFilter getPluginFilter()
      Return a plugin filter which filter the available plugins
      java.lang.Object getPluginLoadError​(java.lang.String id)
      Get the cause because a plugin was not loaded.
      <T> T getSingleInstance​(java.lang.Class<T> interfaceClass)
      Get a single instance of a specific type.
      <T extends NamedExtension>
      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.io.File getTempDir()
      FOR INTERNAL USE ONLY Get the temp directory and clear it from old files.
      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.
      void init​(com.inet.plugin.ServerPluginDescription core)
      FOR INTERNAL USE ONLY Initialize the ServerPluginManager and start the live cycle of the plugins.
      void init​(java.lang.String corePluginId)
      FOR INTERNAL USE ONLY Initialize the ServerPluginManager and start the live cycle of the plugins.
      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.
      com.inet.plugin.ServerPluginDescription loadCoreServerPluginDescriptionForServerStart​(java.lang.String coreID)
      Get the core server plugin for recovery and process starter.
      protected java.util.Map<java.lang.String,​com.inet.plugin.ServerPluginDescription> loadDirectory​(com.inet.plugin.fs.ResourceFile pluginsDir)
      FOR INTERNAL USE ONLY Durchgang #1 : plugins erst mal initial einlesen
      protected java.util.Map<java.lang.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​(java.lang.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​(java.lang.String id, java.util.function.Supplier<com.inet.plugin.Executable> pluginRegisterSupplier)
      Runs the plugin register supplier when the plugin with the given id is loaded.
      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​(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​(com.inet.plugin.fs.ResourceFile pluginDir)
      Set the relative or absolute plugin directory which is to be searched for plugins.
      void setPluginDir​(java.lang.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​(java.lang.String id, java.lang.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 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

      • 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​(java.lang.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:
        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 <T> 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)
        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:
        java.lang.IllegalStateException - if the State of the ServerPluginManager is differ from ServerPluginManager.ServerPluginManagerState.INIT
        Since:
        inetcore 1.0

      • getSingleInstance

        @Nonnull
public <T> T getSingleInstance​(java.lang.Class<T> interfaceClass)
                        throws java.lang.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:
        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 extends NamedExtension> 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.
        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:
        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> T getOptionalInstance​(java.lang.Class<T> interfaceClass)
                          throws java.lang.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:
        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

      • addExtractedPlugin

        public boolean addExtractedPlugin​(@Nonnull
                                  java.lang.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

        public void init​(com.inet.plugin.ServerPluginDescription core)
        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:
        java.lang.IllegalStateException - if the State of the ServerPluginManager is ServerPluginManager.ServerPluginManagerState.INIT
        Since:
        inetcore 3.1

      • init

        public void init​(java.lang.String corePluginId)
        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:
        java.lang.IllegalStateException - if the State of the ServerPluginManager is ServerPluginManager.ServerPluginManagerState.INIT
        Since:
        inetcore 5.1

      • 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

      • getTempDir

        public java.io.File getTempDir()
        FOR INTERNAL USE ONLY Get the temp directory and clear it from old files.
        Returns:
        the directory

      • readPluginsFromDirectory

        protected java.util.Map<java.lang.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 java.util.Map<java.lang.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​(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. 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:
        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

      • runIfPluginLoaded

        public void runIfPluginLoaded​(java.lang.String id,
                              java.util.function.Supplier<com.inet.plugin.Executable> pluginRegisterSupplier)
        Runs the plugin register supplier when the plugin with the given id is loaded.
        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 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

      • setPluginLoadError

        public void setPluginLoadError​(java.lang.String id,
                               java.lang.Throwable th)
        Set the cause because a plugin was not loaded.
        Parameters:
        id - the plugin ID
        th - the cause
        Since:
        23.4

      • 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

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

      • 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

      • getPluginDescription

        public com.inet.plugin.ServerPluginDescription getPluginDescription​(java.lang.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 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

      • findCoreServerPluginDescriptionWithoutLoadingForServerStart

        @Nullable
protected com.inet.plugin.ServerPluginDescription findCoreServerPluginDescriptionWithoutLoadingForServerStart​(@Nullable
                                                                                                              java.lang.String coreID,
                                                                                                              @Nonnull
                                                                                                              com.inet.logging.Logger logger)
                                                                                                       throws java.lang.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:
        java.lang.Exception - if any error occur on loading the plugin
        java.lang.IllegalStateException - if call after init the plugin manager
        Since:
        20.4

      • loadCoreServerPluginDescriptionForServerStart

        @Nullable
public com.inet.plugin.ServerPluginDescription loadCoreServerPluginDescriptionForServerStart​(@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

      • getDiagnostic

        @Nonnull
public static java.lang.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