org.mdi.plugins

Class PluginsManager

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.

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

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.
java.net.URLClassLoader	getClassloader() Return the classLoader used to load the plugins.
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	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 MDIPlugins.
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