PluginsManager (MDIFramework API)

java.lang.Object
- org.mdi.plugins.PluginsManager

```
public class PluginsManager
extends java.lang.Object
```
This class loads and registers the Plugins associated with the application.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class PluginsManager.PluginPeer
This class represents a Plugin in the application.

Nested Classes
Modifier and Type	Class and Description
`static class`	`PluginsManager.PluginPeer` This class represents a Plugin in the application.

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`KEY_PLUGIN_CLASS` "MDIPluginClass":The Plugin ClassPath manifest key.
`static java.lang.String`	`KEY_PLUGIN_DEPENDENCIES` "MDIPluginDependencies": The manifest key to set the list of other Plugins on which this Plugin is dependant on.
`static java.lang.String`	`KEY_PLUGIN_TYPE` "MDIPluginType":The Plugin type manifest key.
`static java.net.URL`	`PLUGINS_XSD` The Plugins XML configuration file Schema.

Constructor Summary

Constructors
Constructor and Description
`PluginsManager(java.io.File pluginsDir)` Constructor, with only one directory containing the Plugins paths.
`PluginsManager(java.io.File pluginsDir, java.io.File pluginsConfig)` Constructor, with only one directory containing the Plugins paths.
`PluginsManager(java.util.List<java.net.URL> pluginsDirList)` Constructor, with as many URLs as necessary containing the Plugins paths.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addListener(PluginsListener listener)` Add a Plugin Listener.
`void`	`applyCommandLineArguments()` Apply the launch arguments.
`void`	`dispose()` Ask each Plugin to dispose of its resources.
`void`	`emitException(java.lang.Throwable e, java.lang.String message, short type)` Emit an exception.
`void`	`emitException(java.lang.Throwable e, java.lang.String message, java.lang.String name, short type)` Emit an exception for a Plugin.
`boolean`	`executeCustomAction(java.lang.String actionName, short blockingType, java.lang.Object... arguments)` Execute a custom action.
`java.net.URLClassLoader`	`getClassloader()` Return the classLoader used to load the plugins.
`java.util.Map<java.lang.String,java.lang.Short>`	`getCustomActions()` Return the custom actions.
`java.util.Map<java.lang.String,java.lang.Boolean>`	`getEnabledPlugins()` Returned the enabled Plugins of this application.
`java.util.Map<java.lang.String,Plugin>`	`getLoadedPluginList()` Return the list of available Plugins, for the plugins who have successfuly been loaded.
`java.util.List<Plugin>`	`getLoadedPlugins()` Return the list of loaded Plugins.
`MDIApplication`	`getMDIApplication()` Return the application.
`java.util.Map<java.lang.String,PluginsManager.PluginPeer>`	`getPluginList()` Return the list of available Plugins.
`int`	`getPluginsSize()` Return the number of loaded Plugins.
`java.io.File`	`getStartDirectory()` Return the starting directory.
`void`	`initAfterGUI(MDIApplication app)` Called after the GUI initialization.
`void`	`initPlugins(MDIApplication app)` Initialize all plugins.
`java.lang.Object`	`loadAndInstanciatePluginClass(java.lang.String name)` Load a class found in a Plugin, and create a new instance from this class.
`java.lang.Class<?>`	`loadPluginClass(java.lang.String name)` Load a class found in a Plugin.
`void`	`registerPlugins(MDIApplication app)` Register all Plugins.
`void`	`removeListener(PluginsListener listener)` Remove a Plugin listener.
`void`	`resetPluginSettings()` Reset all the Plugins Settings.
`void`	`setAdditionalPluginTypes(java.util.Map<java.lang.String,AppliManifestType> additionalPluginTypes)` Set additional Plugin types for the Plugin manager.
`void`	`setAllowedPluginTypes(java.util.Map<java.lang.String,java.lang.Boolean> allowedPluginTypes)` Set the allowed Plugins Types for the Plugin manager.
`void`	`setApplicationID(java.lang.String applicationID)` Set the Application ID.
`void`	`setCustomActions(java.util.Map<java.lang.String,java.lang.Short> customActions)` Add a custom action.
`void`	`setEnabledPlugins(java.util.Map<java.lang.String,java.lang.Boolean> enabledPlugins)` Returned the enabled Plugins of this application.
`void`	`setManagerListener(PluginsManagerListener listener)` Set a listener which will be fired for each exception encountered during the Plugins loading, or some informations on the Plugins loading.
`void`	`setMDIApplication(MDIApplication app)` Set the application.
`void`	`setPluginsEDTSupport(PluginsEDTSupport pluginsEDTSupport)` Set the initialization support of the `MDIPlugin`s.
`void`	`setProgress(ProgressInterface progress, int progressMax)` Configure the Progress bar during the Plugins loading and initialization.
`void`	`setStartDirectory(java.io.File dir)` Set the starting directory.

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

- Field Detail
  - PLUGINS_XSD
```
public static final java.net.URL PLUGINS_XSD
```
    The Plugins XML configuration file Schema.
  - KEY_PLUGIN_TYPE
```
public static final java.lang.String KEY_PLUGIN_TYPE
```
    "MDIPluginType":The Plugin type manifest key. This is used to retrict the allowed Plugins depending on their type. The list of allowed Types can be set through the setAllowedPluginTypes(java.util.Map) method. Plugins which are not allowed will not be loaded by the PluginsManager.
    
    See Also:
    
    setAllowedPluginTypes(java.util.Map), Constant Field Values
  - KEY_PLUGIN_CLASS
```
public static final java.lang.String KEY_PLUGIN_CLASS
```
    "MDIPluginClass":The Plugin ClassPath manifest key. This key must have one of the following formats:
    - <ClassPath declaration> (for example "org.package.Class")
    - (<appliID>:<ClassPath declaration>)(<appliID>:<ClassPath declaration>)*
    In the second case, the Plugin ClassPath will be chosen depending on the setApplicationID(java.lang.String) value.
    Examples
```
 MDIPluginClass: org.mypackage.MyClass
 
```
    In this case the parser will return org.mypackage.MyClass in all cases.
```
 MDIPluginClass: appli:org.mypackage.MyClass
 
```
    In this case the parser will return "org.mypackage.MyClass" if the PluginManager is initialized with "appli" or null, and null in all other cases.
```
 MDIPluginClass: appli:org.mypackage.MyClass;appli2:org.mypackage.MyClass2
 
```
    In this case the parser will return "org.mypackage.MyClass" if the parser is initialized with "appli" or null, "org.mypackage.MyClass2" if the parser is initialized with "appli2", and null in all other cases.
    See Also:
    
    Constant Field Values
  - KEY_PLUGIN_DEPENDENCIES
```
public static final java.lang.String KEY_PLUGIN_DEPENDENCIES
```
    "MDIPluginDependencies": The manifest key to set the list of other Plugins on which this Plugin is dependant on. If one of the Plugins on this list is not loaded, this Plugin will not be loaded too. Note that contrary to the PluginElementTypes.PROPERTY_DEPEND property, the manage won't even try to load the Plugin if a Plugin on which the associated Plugin depends on is not present. Note that:
    - The list of Plugins is separated by ";" characters
    - Each Plugin is characterized by the ClassPath of its loaded Class (see KEY_PLUGIN_CLASS)
    Examples
    
    Simple example
    Lets define one Plugin with the following manifest declaration:
```
 MDIPluginClass: org.package1.plugin1
 
```
    And another one with the following manifest declarations:
```
 MDIPluginClass: org.package2.plugin2
 MDIPluginDependencies: org.package1.plugin1
 
```
    The second Plugin will only be loaded if the first one is found and loaded.
    Example with two dependencies
    Lets define two Plugins with the following manifest declarations:
```
 MDIPluginClass: org.package1.plugin1
 
```
    and:
```
 MDIPluginClass: org.package2.plugin2
 
```
    And a last one with the following manifest declarations:
```
 MDIPluginClass: org.package3.plugin3
 MDIPluginDependencies: org.package1.plugin1;org.package2.plugin2
 
```
    Example with a Plugin type
    Lets define one Plugin with the following manifest declaration:
```
 MDIPluginClass: appli1:org.package1.plugin1;appli2:org.package1.plugin2
 
```
    And another one with the following manifest declarations:
```
 MDIPluginClass: org.package3.plugin3
 MDIPluginDependencies: org.package1.plugin1
 
```
    The second Plugin will only be loaded if the first one is found and loaded, wheach means that it won't be loaded if the application ID is different from "appli1".
    See Also:
    
    Constant Field Values
- Constructor Detail
  - PluginsManager
```
public PluginsManager(java.io.File pluginsDir,
                      java.io.File pluginsConfig)
```
    Constructor, with only one directory containing the Plugins paths. The path for the each main Plugin class is defined in a XML File.
    The Schema of the File is:
```
 <xs:element name="Plugins">
   <xs:complexType>
     <xs:sequence>
       <xs:element maxOccurs="unbounded" ref="plugin" />
     </xs:sequence>
   </xs:complexType>
 </xs:element>
 <xs:element name="plugin">
   <xs:complexType>
     <xs:attribute name="mainclass" type="xs:string" use="required" />
     <xs:attribute name="desc" type="xs:string" />
   </xs:complexType>
 </xs:element>
 
```
    Example, for one Plugin:
```
 <Plugins>
   <plugin mainclass="org.mdi.examples.simple.plugins.OpenImagePlugin" desc="OpenImagePlugin" />
 </Plugins>
 
```
    Parameters:
    
    pluginsDir - the directory were to look for Plugins packaged as Jar Files
    
    pluginsConfig - the XML File name used to define the path to the Plugin classes
  - PluginsManager
```
public PluginsManager(java.util.List<java.net.URL> pluginsDirList)
```
    Constructor, with as many URLs as necessary containing the Plugins paths. The path for the each main Plugin class is in the Plugin Manifest.
    The Manifest contain several specific attributes:
    - MDIPluginType: (optional) The Plugin Type
    - MDIPluginClass: (mandatory) The path to the Plugin class
    - MDIPluginDependencies: (optional) The paths of the Plugins on which a Plugin depend on
    Parameters:
    
    pluginsDirList - the URL list listing directories containing the plugins, or the plugins Jar themselves
  - PluginsManager
```
public PluginsManager(java.io.File pluginsDir)
```
    Constructor, with only one directory containing the Plugins paths. The path for the each main Plugin class is in the Plugin Manifest.
    The Manifest contain several specific attributes:
    - MDIPluginType: (optional) The Plugin Type
    - MDIPluginClass: (mandatory) The path to the Plugin class
    - MDIPluginDependencies: (optional) The paths of the Plugins on which a Plugin depend on
    Parameters:
    
    pluginsDir - the directory were to look for Plugins packaged as Jar Files
- Method Detail
  - setMDIApplication
```
public void setMDIApplication(MDIApplication app)
```
    Set the application.
    
    Parameters:
    
    app - the application
  - getMDIApplication
```
public MDIApplication getMDIApplication()
```
    Return the application.
    
    Returns:
    
    the application
  - setStartDirectory
```
public void setStartDirectory(java.io.File dir)
```
    Set the starting directory. Default is null.
    
    Parameters:
    
    dir - the starting directory
  - getStartDirectory
```
public java.io.File getStartDirectory()
```
    Return the starting directory. Return null by default.
    
    Returns:
    
    the starting directory
  - setPluginsEDTSupport
```
public void setPluginsEDTSupport(PluginsEDTSupport pluginsEDTSupport)
```
    Set the initialization support of the MDIPlugins.
    
    Parameters:
    
    pluginsEDTSupport - the EDT support
    
    See Also:
    
    MDIPluginsInitMode
  - setManagerListener
```
public void setManagerListener(PluginsManagerListener listener)
```
    Set a listener which will be fired for each exception encountered during the Plugins loading, or some informations on the Plugins loading.
    
    Parameters:
    
    listener - the listener
  - setApplicationID
```
public void setApplicationID(java.lang.String applicationID)
```
    Set the Application ID.
    
    Parameters:
    
    applicationID - the Application ID
  - setProgress
```
public void setProgress(ProgressInterface progress,
                        int progressMax)
```
    Configure the Progress bar during the Plugins loading and initialization.
    
    Parameters:
    
    progress - the Progress bar
    
    progressMax - the maximum value of the progress bar at the end of the initialization
  - setAdditionalPluginTypes
```
public void setAdditionalPluginTypes(java.util.Map<java.lang.String,AppliManifestType> additionalPluginTypes)
```
    Set additional Plugin types for the Plugin manager. Contrary to the allowed Plugin Types (see setAllowedPluginTypes(java.util.Map), the manifest key for these types is up to the application. It allows to define additional constraints which will define if Plugins will be loaded.
    Example
    If the additional Plugin types contain only one element:
    - ui => swing (default swing)
    Then considering the following plugins and their manifest:
    - If the manifest does not contain an attribute for the key "ui": the Plugin will be loaded
    - If the manifest does contain an attribute for the key "ui", with the value "swing": the Plugin will be loaded
    - If the manifest does contain an attribute for the key "ui", with the value "swing;swt": the Plugin will be loaded
    - If the manifest does contain an attribute for the key "ui", with the value "swt": the Plugin will not be loaded
    Another example
    If the additional Plugin types contain only one element:
    - ui => swing (no default value)
    Then considering the following plugins and their manifest:
    - If the manifest does not contain an attribute for the key "ui": the Plugin will not be loaded
    - If the manifest does contain an attribute for the key "ui", with the value "swing": the Plugin will be loaded
    - If the manifest does contain an attribute for the key "ui", with the value "swing;swt": the Plugin will be loaded
    - If the manifest does contain an attribute for the key "ui", with the value "swt": the Plugin will not be loaded
    Parameters:
    
    additionalPluginTypes - the Map of additional Plugin types
  - setAllowedPluginTypes
```
public void setAllowedPluginTypes(java.util.Map<java.lang.String,java.lang.Boolean> allowedPluginTypes)
```
    Set the allowed Plugins Types for the Plugin manager. Plugin Types are String IDs that can be retrieved in the Plugins Manifests by the key "MDIPluginType". Only Plugins whose types has been allowed will be loaded by the manager.
    Examples
    If the allowed Plugin types are the Map:
    - appli => true
    - common => true
    Then considering the following plugins and their manifest:
    - If the manifest does not contain an attribute for the key "MDIPluginType": the Plugin will not be loaded
    - If the manifest does contain an attribute for the key "MDIPluginType", with the value "common": the Plugin will be loaded
    - If the manifest does contain an attribute for the key "MDIPluginType", with the value "test": the Plugin will not be loaded
    Parameters:
    
    allowedPluginTypes - the allowed Plugin Types as a Map
    
    See Also:
    
    setAdditionalPluginTypes(java.util.Map)
  - getClassloader
```
public java.net.URLClassLoader getClassloader()
```
    Return the classLoader used to load the plugins.
    
    Returns:
    
    the classLoader used to load the plugins
  - loadPluginClass
```
public java.lang.Class<?> loadPluginClass(java.lang.String name)
```
    Load a class found in a Plugin.
    It is necessary to use this method to load any classes found in Plugins, except the core class that implements the Plugin interface, because only the PluginManager get holds of the classLoader that is able to load all the Plugins
    
    Parameters:
    
    name - the class name
    
    Returns:
    
    the Plugin class
  - emitException
```
public void emitException(java.lang.Throwable e,
                          java.lang.String message,
                          short type)
```
    Emit an exception.
    
    Parameters:
    
    e - the throwable
    
    message - the message
    
    type - the exception type
  - emitException
```
public void emitException(java.lang.Throwable e,
                          java.lang.String message,
                          java.lang.String name,
                          short type)
```
    Emit an exception for a Plugin.
    
    Parameters:
    
    e - the throwable
    
    message - the message
    
    name - the plugin name
    
    type - the exception type
  - initAfterGUI
```
public void initAfterGUI(MDIApplication app)
```
    Called after the GUI initialization. Will call MDIPlugin.initAfterGUI(org.mdi.bootstrap.MDIApplication) for each MDIPlugin.
    
    Parameters:
    
    app - the MDIApplication
  - applyCommandLineArguments
```
public void applyCommandLineArguments()
```
    Apply the launch arguments.
  - loadAndInstanciatePluginClass
```
public java.lang.Object loadAndInstanciatePluginClass(java.lang.String name)
```
    Load a class found in a Plugin, and create a new instance from this class.
    
    Parameters:
    
    name - the class name
    
    Returns:
    
    the Plugin instance
    
    See Also:
    
    loadPluginClass(String)
  - addListener
```
public void addListener(PluginsListener listener)
```
    Add a Plugin Listener.
    
    Parameters:
    
    listener - the Plugin Listener
  - removeListener
```
public void removeListener(PluginsListener listener)
```
    Remove a Plugin listener.
    
    Parameters:
    
    listener - the Plugin Listener
  - getPluginsSize
```
public int getPluginsSize()
```
    Return the number of loaded Plugins.
    
    Returns:
    
    the number of loaded Plugins
  - resetPluginSettings
```
public void resetPluginSettings()
```
    Reset all the Plugins Settings.
  - initPlugins
```
public void initPlugins(MDIApplication app)
```
    Initialize all plugins.
    
    Parameters:
    
    app - the Application
  - registerPlugins
```
public void registerPlugins(MDIApplication app)
                     throws org.xml.sax.SAXException,
                            java.io.IOException
```
    Register all Plugins. The registration of Plugins follows these steps:
    - create a new URLClassLoader associated with all the Jar Files in the plugins directory
    - parse the XML file defining each Plugin class
    - create a new instance for each of the previous classes
    - add this class to the list of Plugins
    Parameters:
    
    app - the Application
    
    Throws:
    
    org.xml.sax.SAXException - if a SAXException is encountered while registering the Plugins
    
    java.io.IOException - if an IOException is encountered while registering the Plugins
  - getLoadedPlugins
```
public java.util.List<Plugin> getLoadedPlugins()
```
    Return the list of loaded Plugins.
    
    Returns:
    
    the list of loaded Plugins
    
    See Also:
    
    getPluginList()
  - getPluginList
```
public java.util.Map<java.lang.String,PluginsManager.PluginPeer> getPluginList()
```
    Return the list of available Plugins. Each element is a PluginsManager.PluginPeer. A Plugin in the plugin configuration file will be added in this list if the loading process of the Plugin main class is successful. However, the Plugin will really be loaded (and associated actions created) only if it have been enabled.
    
    Returns:
    
    the list of available Plugins
    
    See Also:
    
    getLoadedPlugins(), getLoadedPluginList()
  - dispose
```
public void dispose()
```
    Ask each Plugin to dispose of its resources.
  - getLoadedPluginList
```
public java.util.Map<java.lang.String,Plugin> getLoadedPluginList()
```
    Return the list of available Plugins, for the plugins who have successfuly been loaded. Each element is a Plugin.
    
    Returns:
    
    the loaded Plugins Map
    
    See Also:
    
    getLoadedPlugins()
  - setEnabledPlugins
```
public void setEnabledPlugins(java.util.Map<java.lang.String,java.lang.Boolean> enabledPlugins)
```
    Returned the enabled Plugins of this application. The Map maps plugin names to the Boolean value determining if they are enabled.
    
    Parameters:
    
    enabledPlugins - the enabled Plugins
  - getEnabledPlugins
```
public java.util.Map<java.lang.String,java.lang.Boolean> getEnabledPlugins()
```
    Returned the enabled Plugins of this application.
    
    Returns:
    
    the enabled Plugins
  - setCustomActions
```
public void setCustomActions(java.util.Map<java.lang.String,java.lang.Short> customActions)
```
    Add a custom action.
    
    Parameters:
    
    customActions - the custom actions
  - getCustomActions
```
public java.util.Map<java.lang.String,java.lang.Short> getCustomActions()
```
    Return the custom actions.
    
    Returns:
    
    the custom actions
  - executeCustomAction
```
public boolean executeCustomAction(java.lang.String actionName,
                                   short blockingType,
                                   java.lang.Object... arguments)
```
    Execute a custom action.
    
    Parameters:
    
    actionName - the custom action name
    
    blockingType - the blocking type
    
    arguments - the arguments
    
    Returns:
    
    true if a plugin executed the custom action

Class PluginsManager

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PLUGINS_XSD

KEY_PLUGIN_TYPE

KEY_PLUGIN_CLASS

Examples

KEY_PLUGIN_DEPENDENCIES

Examples

Simple example

Example with two dependencies

Example with a Plugin type

Constructor Detail

PluginsManager

PluginsManager

PluginsManager

Method Detail

setMDIApplication

getMDIApplication

setStartDirectory

getStartDirectory

setPluginsEDTSupport

setManagerListener

setApplicationID

setProgress

setAdditionalPluginTypes

Example

Another example

setAllowedPluginTypes

Examples

getClassloader

loadPluginClass

emitException

emitException

initAfterGUI

applyCommandLineArguments

loadAndInstanciatePluginClass

addListener

removeListener

getPluginsSize

resetPluginSettings

initPlugins

registerPlugins

getLoadedPlugins

getPluginList

dispose

getLoadedPluginList

setEnabledPlugins

getEnabledPlugins

setCustomActions

getCustomActions

executeCustomAction