org.dspace.core

Class PluginManager

java.lang.Object

org.dspace.core.PluginManager

public class PluginManager
extends Object

The Plugin Manager is a very simple component container. It creates and organizes components (plugins), and helps select a plugin in the cases where there are many possible choices. It also gives some limited control over the lifecycle of a plugin. It manages three different types (usage patterns) of plugins:

1. Singleton Plugin
   There is only one implementation class for the plugin. It is indicated in the configuration. This type of plugin chooses an implementations of a service, for the entire system, at configuration time. Your application just fetches the plugin for that interface and gets the configured-in choice.

2. Sequence Plugins
   You need a sequence or series of plugins, to implement a mechanism like StackableAuthenticationMethods or a pipeline, where each plugin is called in order to contribute its implementation of a process to the whole.

3. Named Plugins
   Use a named plugin when the application has to choose one plugin implementation out of many available ones. Each implementation is bound to one or more names (symbolic identifiers) in the configuration.

The name is just a String to be associated with the combination of implementation class and interface. It may contain any characters except for comma (,) and equals (=). It may contain embedded spaces. Comma is a special character used to separate names in the configuration entry.

Version:

$Revision$

Author:

Larry Stone

See Also:

SelfNamedPlugin

Constructor Summary

Constructors

Constructor and Description
PluginManager()

Method Summary

Methods

Modifier and Type	Method and Description
static void	checkConfiguration() Validate the entries in the DSpace Configuration relevant to PluginManager.
static String[]	getAllPluginNames(Class intfc) Returns all of the names under which a named plugin implementing the interface intface can be requested (with getNamedPlugin()).
static String[]	getAllPluginNames(String module, Class intfc) Returns all of the names under which a named plugin implementing the interface intface can be requested (with getNamedPlugin()).
static Object	getNamedPlugin(Class intfc, String name) Returns an instance of a plugin that implements the interface intface and is bound to a name matching name.
static Object	getNamedPlugin(String module, Class intfc, String name) Returns an instance of a plugin that implements the interface intface and is bound to a name matching name.
static Object[]	getPluginSequence(Class intfc) Returns instances of all plugins that implement the interface intface, in an Array.
static Object[]	getPluginSequence(String module, Class intfc) Returns instances of all plugins that implement the interface intface, in an Array.
static Object	getSinglePlugin(Class interfaceClass) Returns an instance of the singleton (single) plugin implementing the given interface.
static Object	getSinglePlugin(String module, Class interfaceClass) Returns an instance of the singleton (single) plugin implementing the given interface.
static boolean	hasNamedPlugin(Class intfc, String name) Returns whether a plugin exists which implements the specified interface and has a specified name.
static boolean	hasNamedPlugin(String module, Class intfc, String name) Returns whether a plugin exists which implements the specified interface and has a specified name.
static void	main(String[] argv) Invoking this class from the command line just runs checkConfiguration and shows the results.
static void	releasePlugin(Object plugin) Tells the Plugin Manager to let go of any references to a reusable plugin, to prevent it from being given out again and to allow the object to be garbage-collected.

Methods inherited from class java.lang.Object

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

Constructor Detail

PluginManager

public PluginManager()

Method Detail

getSinglePlugin

public static Object getSinglePlugin(Class interfaceClass)
                              throws PluginConfigurationError,
                                     PluginInstantiationException

Returns an instance of the singleton (single) plugin implementing the given interface. There must be exactly one single plugin configured for this interface, otherwise the PluginConfigurationError is thrown.

Note that this is the only "get plugin" method which throws an exception. It is typically used at initialization time to set up a permanent part of the system so any failure is fatal.

Parameters:

interfaceClass - interface Class object

Returns:

instance of plugin

Throws:

PluginConfigurationError

PluginInstantiationException

getSinglePlugin

public static Object getSinglePlugin(String module,
                     Class interfaceClass)
                              throws PluginConfigurationError,
                                     PluginInstantiationException

Returns an instance of the singleton (single) plugin implementing the given interface. There must be exactly one single plugin configured for this interface, otherwise the PluginConfigurationError is thrown.

Note that this is the only "get plugin" method which throws an exception. It is typically used at initialization time to set up a permanent part of the system so any failure is fatal.

Parameters:

module - name of config module, or null for standard location

interfaceClass - interface Class object

Returns:

instance of plugin

Throws:

PluginConfigurationError

PluginInstantiationException

getPluginSequence

public static Object[] getPluginSequence(Class intfc)
                                  throws PluginInstantiationException

Returns instances of all plugins that implement the interface intface, in an Array. Returns an empty array if no there are no matching plugins.

The order of the plugins in the array is the same as their class names in the configuration's value field.

Parameters:

intfc - interface for which to find plugins.

Returns:

an array of plugin instances; if none are available an empty array is returned.

Throws:

PluginInstantiationException

getPluginSequence

public static Object[] getPluginSequence(String module,
                         Class intfc)
                                  throws PluginInstantiationException

Returns instances of all plugins that implement the interface intface, in an Array. Returns an empty array if no there are no matching plugins.

The order of the plugins in the array is the same as their class names in the configuration's value field.

Parameters:

module - name of config module, or null for standard

intfc - interface for which to find plugins.

Returns:

an array of plugin instances; if none are available an empty array is returned.

Throws:

PluginInstantiationException

getNamedPlugin

public static Object getNamedPlugin(Class intfc,
                    String name)
                             throws PluginInstantiationException

Returns an instance of a plugin that implements the interface intface and is bound to a name matching name. If there is no matching plugin, it returns null. The names are matched by String.equals().

Parameters:

intfc - the interface class of the plugin

name - under which the plugin implementation is configured.

Returns:

instance of plugin implementation, or null if there is no match or an error.

Throws:

PluginInstantiationException

getNamedPlugin

public static Object getNamedPlugin(String module,
                    Class intfc,
                    String name)
                             throws PluginInstantiationException

Returns an instance of a plugin that implements the interface intface and is bound to a name matching name. If there is no matching plugin, it returns null. The names are matched by String.equals().

Parameters:

module - config module, or null for standard location

intfc - the interface class of the plugin

name - under which the plugin implementation is configured.

Returns:

instance of plugin implementation, or null if there is no match or an error.

Throws:

PluginInstantiationException

hasNamedPlugin

public static boolean hasNamedPlugin(Class intfc,
                     String name)
                              throws PluginInstantiationException

Returns whether a plugin exists which implements the specified interface and has a specified name. If a matching plugin is found to be configured, return true. If there is no matching plugin, return false.

Parameters:

intfc - the interface class of the plugin

name - under which the plugin implementation is configured.

Returns:

true if plugin was found to be configured, false otherwise

Throws:

PluginInstantiationException

hasNamedPlugin

public static boolean hasNamedPlugin(String module,
                     Class intfc,
                     String name)
                              throws PluginInstantiationException

Returns whether a plugin exists which implements the specified interface and has a specified name. If a matching plugin is found to be configured, return true. If there is no matching plugin, return false.

Parameters:

module - the config module or null for regular location

intfc - the interface class of the plugin

name - under which the plugin implementation is configured.

Returns:

true if plugin was found to be configured, false otherwise

Throws:

PluginInstantiationException

getAllPluginNames

public static String[] getAllPluginNames(Class intfc)

Returns all of the names under which a named plugin implementing the interface intface can be requested (with getNamedPlugin()). The array is empty if there are no matches. Use this to populate a menu of plugins for interactive selection, or to document what the possible choices are.

NOTE: The names are NOT returned in any deterministic order.

Parameters:

intfc - plugin interface for which to return names.

Returns:

an array of strings with every name; if none are available an empty array is returned.

getAllPluginNames

public static String[] getAllPluginNames(String module,
                         Class intfc)

Returns all of the names under which a named plugin implementing the interface intface can be requested (with getNamedPlugin()). The array is empty if there are no matches. Use this to populate a menu of plugins for interactive selection, or to document what the possible choices are.

NOTE: The names are NOT returned in any deterministic order.

Parameters:

module - the module name

intfc - plugin interface for which to return names.

Returns:

an array of strings with every name; if none are available an empty array is returned.

releasePlugin

public static void releasePlugin(Object plugin)

Tells the Plugin Manager to let go of any references to a reusable plugin, to prevent it from being given out again and to allow the object to be garbage-collected. Call this when a plugin instance must be taken out of circulation.

Parameters:

plugin - the object to release, must have been created by getNamedPlugin etc.

checkConfiguration

public static void checkConfiguration()
                               throws IOException

Validate the entries in the DSpace Configuration relevant to PluginManager. Look for inconsistencies, illegal syntax, etc. Announce violations with "log.error" so they appear in the log or in the standard error stream if this is run interactively.

• Look for duplicate keys (by parsing the config file)
• Interface in plugin.single, plugin.sequence, plugin.named, plugin.selfnamed is valid.
• Classname in plugin.reusable exists and matches a plugin config.
• Classnames in config values exist.
• Classnames in plugin.selfnamed loads and is subclass of SelfNamedPlugin
• Implementations of named plugin have no name collisions.
• Named plugin entries lacking names.

Throws:

IOException

main

public static void main(String[] argv)
                 throws Exception

Invoking this class from the command line just runs checkConfiguration and shows the results. There are no command-line options.

Throws:

Exception