ilog.views.appframe.plugin

Class IlvPluginManager

java.lang.Object

ilog.views.appframe.plugin.IlvPluginManager

public class IlvPluginManager
extends Object

A plug-in manager is responsible for creating, initializing, and installing a set of IlvPlugin. It also saves and restores the settings of the plug-ins from the user settings of the application. For example, it saves in the user settings if the plug-ins were installed during the last application session.

Where are the plug-ins of an application?
A plug-in manager finds its plug-ins in a root directory that is accessed with the methods setRootDirectory(java.io.File) and getRootDirectory(). Basically, one plug-in is defined for each subdirectory of this root directory. In each subdirectory, the plug-in manager looks for a plugin.xml file that defines the plug-in. If no such file is found, the directory is not considered to contain a plug-in.

A plugin can also be contained in a jar. In this case, the method setRootDirectory(java.io.File) cannot be used. Instead, the location of the file plugin.xml inside the jar must be given to the manager as root URL with the method setRootURL(java.net.URL).

How to create a plug-in manager?
Here is a schematic code example that creates and initializes a plug-in manager. The plug-ins are contained in a root directory:

 java.io.File pluginsRootDirectory = ...
 IlvApplication application = ...
 ...
 IlvPluginManager pluginManager = new IlvPluginManager();
 pluginManager.setRootDirectory(pluginsRootDirectory);
 pluginManager.setApplication(application);
 ...
 application.initialize();
 

Here is a schematic code example for the case that the plug-in is contained inside a jar file:

 java.net.URL pluginURL = getClass().getResource("plugin.xml");
 IlvApplication application = ...
 ...
 IlvPluginManager pluginManager = new IlvPluginManager();
 pluginManager.setRootURL(pluginURL);
 pluginManager.setApplication(application);
 ...
 application.initialize();
 

It is important that a plug-in is initialized and set to an application before the application is initialized. The plug-in manager must be able to add the resource files (settings and internationalization files) of its plug-ins before the application initializes the components that depend on those settings. (See IlvApplication.initialize().)

You can find documentation and examples of using plug-ins in the Perforce JViews Application Framework User's Manual, in the chapter on Plug-ins.

See Also:

IlvPlugin

Field Summary

Fields

Modifier and Type	Field and Description
static String	INSTALL_BY_DEFAULT Installation mode that specifies that a plug-in should automatically be installed when launching the application.
static String	NEVER_INSTALL_BY_DEFAULT Installation mode that specifies never to install a plug-in by default when launching the application.
static String	NOT_INSTALL_BY_DEFAULT Installation mode that specifies not to install a plug-in by default when launching the application.

Constructor Summary

Constructors

Constructor and Description
IlvPluginManager() Constructs an IlvPluginManager.

Method Summary

Modifier and Type	Method and Description
void	addPluginListener(PluginListener listener) Adds a plug-in listener for receiving plug-in events.
void	addRootDirectory(File directory) Adds the specified directory to the list of directories this plugin manager will scan to find its plugins.
void	addRootURL(URL url) Adds the specified url to the list of root URLs this plugin manager will scan to find its plugins.
protected void	firePluginEvent(PluginEvent event) Fires the specified plug-in event to the plugin listeners registered with this plug-in manager.
IlvApplication	getApplication() Returns the application of the plug-in manager.
IlvPlugin	getPlugin(int index) Returns the plug-in stored at the specified index.
IlvPlugin	getPlugin(String id) Returns the plug-in with the specified ID.
int	getPluginCount() Returns the number of plug-ins of the plug-in manager.
static ArrayList<IlvPluginManager>	getPluginManagers(IlvApplication application) Returns the plugin managers of the application.
IlvPlugin[]	getPlugins() Returns the array of plug-ins owned by the plug-in manager.
IlvPlugin[]	getRequiredPlugins(IlvPlugin plugin) Returns the plug-ins that the specified plugin depends on to be installed.
File	getRootDirectory() Returns the root directory containing all the plug-ins.
File	getRootDirectory(int index) Returns the root directory of this plugin manager at the specified storage index.
int	getRootDirectoryCount() Returns the number of root directories that have been specified to this plugin manager.
URL	getRootURL() Returns the root URL containing all the plug-ins.
URL	getRootURL(int index) Returns the root URL of this plugin manager at the specified storage index.
int	getRootURLCount() Returns the number of root URLs that have been specified to this plugin manager.
IlvSettings	getSettings() Returns the settings that initialize the plug-in manager.
IlvSettingsElement	getSettingsElement() Returns the settings element that provides the settings for this plug-in manager.
IlvSettingsQuery	getSettingsQuery() Returns the query that selects the settings element of the plug-in manager.
boolean	initializedOnUserSettings() Determines whether the plug-in manager has been initialized with the user settings.
boolean	installPlugin(IlvPlugin plugin) Installs the specified plugin.
protected void	invokePluginInstaller(IlvPlugin plugin, boolean install) Invokes the IlvPluginInstaller of the specified plugin.
protected boolean	isInitiallyInstalled(IlvPlugin plugin) Determines whether the specified plug-in should be installed when the application is being launched.
void	readPlugins() Reads the plug-ins of the application.
protected void	readSettings(IlvSettingsElement settingsElement) Reads the settings of the plug-in manager.
void	removePluginListener(PluginListener listener) Removes the specified plug-in listener so that it no longer receives plug-in events.
void	setApplication(IlvApplication application) Sets the application that this plug-in manager will manage the plug-ins for.
void	setRootDirectory(File directory) Sets the root directory containing all the plug-ins.
void	setRootURL(URL url) Sets the root URL containing all the plug-ins.
void	setSettings(IlvSettings settings) Sets the settings of the plug-in manager.
void	setSettingsElement(IlvSettingsElement element) Forces the settings of the plug-in manager to be read and written from the specified settings element.
void	setSettingsQuery(IlvSettingsQuery query) Sets the query that selects the settings element which defines the plug-in manager.
boolean	uninstallPlugin(IlvPlugin plugin, boolean dependentPlugins) Uninstalls the specified plugin.
void	uninstallPlugins() Uninstalls the plug-ins of the plug-in manager.
protected void	writeSettings(IlvSettingsElement settingsElement) Writes the settings of the plug-in manager.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INSTALL_BY_DEFAULT

public static final String INSTALL_BY_DEFAULT

Installation mode that specifies that a plug-in should automatically be installed when launching the application. This is the default mode.

If the plug-in has been uninstalled with the method uninstallPlugin(IlvPlugin, boolean) during the last application session, the plug-in will not be installed automatically and must be explicitly reinstalled with the method installPlugin(IlvPlugin).

See Also:

isInitiallyInstalled(ilog.views.appframe.plugin.IlvPlugin), NOT_INSTALL_BY_DEFAULT, NEVER_INSTALL_BY_DEFAULT, Constant Field Values

NOT_INSTALL_BY_DEFAULT

public static final String NOT_INSTALL_BY_DEFAULT

Installation mode that specifies not to install a plug-in by default when launching the application. If the plug-in has been installed with the method installPlugin(IlvPlugin) during the last application session, it will be installed when launching the application.

See Also:

INSTALL_BY_DEFAULT, Constant Field Values

NEVER_INSTALL_BY_DEFAULT

public static final String NEVER_INSTALL_BY_DEFAULT

Installation mode that specifies never to install a plug-in by default when launching the application. The plug-in is not automatically installed, even though it was explicitly installed in the previous application session with the method installPlugin(IlvPlugin).

For example, this mode can be convenient for plug-ins where their installation depends on the arguments given to the application command line.

See Also:

INSTALL_BY_DEFAULT, NOT_INSTALL_BY_DEFAULT, Constant Field Values

Constructor Detail

IlvPluginManager

public IlvPluginManager()

Constructs an IlvPluginManager.

Method Detail

setApplication

public void setApplication(IlvApplication application)

Sets the application that this plug-in manager will manage the plug-ins for.

See Also:

setApplication(ilog.views.appframe.IlvApplication)

getApplication

public IlvApplication getApplication()

Returns the application of the plug-in manager.

See Also:

setApplication(ilog.views.appframe.IlvApplication)

setRootURL

public void setRootURL(URL url)

Sets the root URL containing all the plug-ins. Typically, this is the URL of the root directory of the plug-ins. It can however also be the URL inside a jar that points to the file plugin.xml that describes the plugin. All root URLs previously specified to this plugin manager are erased.

Parameters:

url - The root URL.

Since:

JViews 7.5

See Also:

getRootURL(), addRootURL(URL)

getRootURL

public URL getRootURL()

Returns the root URL containing all the plug-ins.

Since:

JViews 7.5

See Also:

setRootURL(java.net.URL), getRootURL(int)

addRootURL

public void addRootURL(URL url)

Adds the specified url to the list of root URLs this plugin manager will scan to find its plugins. Typically, this is the URL of the root directory of the plug-ins. It can however also be the URL inside a jar that points to the file plugin.xml that describes the plugin.

Parameters:

url - The new root URL of this plugin manager.

Since:

JViews 7.5

See Also:

getRootURL(), setRootURL(java.net.URL)

getRootURLCount

public int getRootURLCount()

Returns the number of root URLs that have been specified to this plugin manager.

Returns:

The number of root URLs of this plugin manager.

Since:

JViews 7.5

See Also:

addRootURL(URL), setRootURL(java.net.URL)

getRootURL

public URL getRootURL(int index)

Returns the root URL of this plugin manager at the specified storage index.

Parameters:

index - The storage index of the root URL to return.

Returns:

The root URL at the specified index. If the specified index exceeds the number of root URLs specified to this plugin manager, this method returns null.

Since:

JViews 7.5

See Also:

addRootURL(URL), setRootURL(java.net.URL), getRootURLCount()

setRootDirectory

public void setRootDirectory(File directory)

Sets the root directory containing all the plug-ins. All root directories previously specified to this plugin manager are erased.

Parameters:

directory - The root file directory.

See Also:

getRootDirectory(), addRootDirectory(java.io.File)

getRootDirectory

public File getRootDirectory()

Returns the root directory containing all the plug-ins. If the root URL does not correspond to any file, this method returns nonsense. Therefore, it is usually safer to use getRootURL().

See Also:

setRootDirectory(java.io.File), getRootDirectory(int)

addRootDirectory

public void addRootDirectory(File directory)

Adds the specified directory to the list of directories this plugin manager will scan to find its plugins.

Parameters:

directory - The new root directory of this plugin manager.

See Also:

getRootDirectory(), setRootDirectory(java.io.File)

getRootDirectoryCount

public int getRootDirectoryCount()

Returns the number of root directories that have been specified to this plugin manager. If root URLs have been added to the plugin manager with addRootURL(URL) that do not correspond to any file, this method returns nonsense. Therefore, it is usually safer to use getRootURLCount() to retrieve the number of root URLs.

Returns:

The number of root directories of this plugin manager.

See Also:

addRootDirectory(java.io.File), setRootDirectory(java.io.File)

getRootDirectory

public File getRootDirectory(int index)

Returns the root directory of this plugin manager at the specified storage index. If root URLs have been added to the plugin manager with addRootURL(URL) that do not correspond to any file, this method returns nonsense. Therefore, it is usually safer to use getRootURL(int) to retrieve the root URL.

Parameters:

index - The storage index of the root directory to return.

Returns:

The root directory at the specified index. If the specified index exceeds the number of root directories specified to this plugin manager, this method returns null.

See Also:

addRootDirectory(java.io.File), setRootDirectory(java.io.File), getRootDirectoryCount()

readPlugins

public void readPlugins()

Reads the plug-ins of the application.
This method is automatically called when the application is initializing. It reads all the plug-ins contained in the root directory, but not yet installed.

isInitiallyInstalled

protected boolean isInitiallyInstalled(IlvPlugin plugin)

Determines whether the specified plug-in should be installed when the application is being launched.

This method checks first whether the plug-in installer of the specified plugin authorizes the installation of the plug-in. If yes, the install mode of the plug-in will be compared with the following values:

• INSTALL_BY_DEFAULT: The plug-in is automatically installed, unless it has been explicitly uninstalled in the previous application session.
• NOT_INSTALL_BY_DEFAULT: The plug-in is not automatically installed, unless it has been explicitly installed in the previous application session.
• NEVER_INSTALL_BY_DEFAULT: The plug-in is never automatically installed.

This method should be overridden for processing user-specific values that can be specified in the "installMode" attribute in the settings defining the specified plug-in.

Returns:

true if the plug-in can be initially installed; false otherwise.

See Also:

IlvPlugin.getInstallMode(), IlvPluginInstaller.canInstall(ilog.views.appframe.IlvApplication, ilog.views.appframe.plugin.IlvPlugin)

uninstallPlugins

public void uninstallPlugins()
                      throws IlvPluginException

Uninstalls the plug-ins of the plug-in manager.

Throws:

IlvPluginException

See Also:

installPlugin(IlvPlugin)

installPlugin

public boolean installPlugin(IlvPlugin plugin)
                      throws IlvPluginException

Installs the specified plugin.

Parameters:

plugin - The plug-in to install.

Returns:

true if the plug-in could be installed; false otherwise.

Throws:

IlvPluginException

See Also:

uninstallPlugin(ilog.views.appframe.plugin.IlvPlugin, boolean)

uninstallPlugin

public boolean uninstallPlugin(IlvPlugin plugin,
                               boolean dependentPlugins)
                        throws IlvPluginException

Uninstalls the specified plugin. If the dependentPlugins parameter is true, all the plug-ins that depend on this plug-in are uninstalled before the specified plug-in.

Parameters:

plugin - The plug-in to uninstall.

dependentPlugins - If true all the plug-ins that depend on the specified plug-in are uninstalled before the specified plug-in is uninstalled; otherwise, only the specified plug-in is uninstalled.

Returns:

true if the plug-in(s) could be uninstalled; false otherwise.

Throws:

IlvPluginException

See Also:

installPlugin(IlvPlugin)

invokePluginInstaller

protected void invokePluginInstaller(IlvPlugin plugin,
                                     boolean install)
                              throws Exception

Invokes the IlvPluginInstaller of the specified plugin.

Parameters:

plugin - The plugin to invoke the plugin installer from.

install - If true, the IlvPluginInstaller.install(ilog.views.appframe.IlvApplication, ilog.views.appframe.plugin.IlvPlugin) method of the plugin installer is called. Otherwise, the IlvPluginInstaller.install(ilog.views.appframe.IlvApplication, ilog.views.appframe.plugin.IlvPlugin) method of the plugin installer is called.

Throws:

Exception

getPluginCount

public int getPluginCount()

Returns the number of plug-ins of the plug-in manager. This number includes plug-ins that are installed and not installed.

See Also:

getPlugin(int), getPlugins()

getPlugins

public IlvPlugin[] getPlugins()

Returns the array of plug-ins owned by the plug-in manager.

See Also:

getPlugin(int), getPluginCount()

getPlugin

public IlvPlugin getPlugin(int index)

Returns the plug-in stored at the specified index.

Parameters:

index - The storage index of the plug-in to return.

Returns:

The plug-in at the specified index.

See Also:

getPlugin(String), getPluginCount()

getPlugin

public IlvPlugin getPlugin(String id)

Returns the plug-in with the specified ID.

Parameters:

id - The ID of the plug-in to return.

Returns:

The plug-in with the specified ID or null if no plug-in could be found with this ID.

See Also:

getPlugin(int)

getRequiredPlugins

public IlvPlugin[] getRequiredPlugins(IlvPlugin plugin)

Returns the plug-ins that the specified plugin depends on to be installed.

Parameters:

plugin - The plug-in to retrieve the required plug-ins from.

Returns:

The array of required plug-ins.

readSettings

protected void readSettings(IlvSettingsElement settingsElement)

Reads the settings of the plug-in manager. By default, this method reads the installation state of the plug-ins that were installed when exiting the previous application session.

Parameters:

settingsElement - The root settings element that contains the settings of the plug-in manager.

See Also:

writeSettings(ilog.views.appframe.settings.IlvSettingsElement)

writeSettings

protected void writeSettings(IlvSettingsElement settingsElement)

Writes the settings of the plug-in manager. By default, this method writes the installation state of all the plug-ins owned by this plug-in manager.

Parameters:

settingsElement - The root settings element for writing the settings of the plug-in manager.

See Also:

readSettings(ilog.views.appframe.settings.IlvSettingsElement)

getSettings

public IlvSettings getSettings()

Returns the settings that initialize the plug-in manager.

Returns:

The settings of the plug-in manager.

See Also:

readSettings(ilog.views.appframe.settings.IlvSettingsElement), setSettings(ilog.views.appframe.settings.IlvSettings)

setSettings

public void setSettings(IlvSettings settings)

Sets the settings of the plug-in manager.

Parameters:

settings - The new settings of the plug-in manager.

See Also:

getSettings(), readSettings(ilog.views.appframe.settings.IlvSettingsElement)

setSettingsQuery

public void setSettingsQuery(IlvSettingsQuery query)

Sets the query that selects the settings element which defines the plug-in manager.

Parameters:

query - The settings query.

See Also:

getSettingsQuery(), readSettings(ilog.views.appframe.settings.IlvSettingsElement), getSettingsElement()

getSettingsQuery

public IlvSettingsQuery getSettingsQuery()

Returns the query that selects the settings element of the plug-in manager.

Returns:

The settings query.

See Also:

setSettingsQuery(ilog.views.appframe.settings.IlvSettingsQuery)

setSettingsElement

public void setSettingsElement(IlvSettingsElement element)

Forces the settings of the plug-in manager to be read and written from the specified settings element. The specified settings element replaces the settings element that is selected by default from the settings given by the method getSettings() with the query getSettingsQuery().

Parameters:

element - The new settings element that provides the settings of the plug-in manager.

See Also:

getSettingsElement(), getSettings(), getSettingsQuery()

getSettingsElement

public IlvSettingsElement getSettingsElement()

Returns the settings element that provides the settings for this plug-in manager.

Returns:

The settings element or null if no settings element could be found.

See Also:

setSettingsElement(ilog.views.appframe.settings.IlvSettingsElement), getSettingsQuery()

initializedOnUserSettings

public boolean initializedOnUserSettings()

Determines whether the plug-in manager has been initialized with the user settings.

Returns:

true if the application has already been launched for the current application user profile; false otherwise.

addPluginListener

public void addPluginListener(PluginListener listener)

Adds a plug-in listener for receiving plug-in events.

Parameters:

listener - The plug-in listener to add.

See Also:

removePluginListener(ilog.views.appframe.plugin.PluginListener)

removePluginListener

public void removePluginListener(PluginListener listener)

Removes the specified plug-in listener so that it no longer receives plug-in events.

Parameters:

listener - The plug-in listener to remove.

See Also:

addPluginListener(ilog.views.appframe.plugin.PluginListener)

firePluginEvent

protected void firePluginEvent(PluginEvent event)

Fires the specified plug-in event to the plugin listeners registered with this plug-in manager.

Parameters:

event - The event to fire.

See Also:

addPluginListener(ilog.views.appframe.plugin.PluginListener)

getPluginManagers

public static ArrayList<IlvPluginManager> getPluginManagers(IlvApplication application)

Returns the plugin managers of the application. This is an array list of IlvPluginManager objects. It can return null if no plugin manager was yet installed at the application.

Since:

JViews 8.7