org.dspace.core
Class PluginManager

java.lang.Object
  extended by 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: 3762 $
Author:
Larry Stone
See Also:
SelfNamedPlugin

Constructor Summary
PluginManager()
           
 
Method Summary
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 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[] getPluginSequence(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 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

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

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

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.

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.

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


Copyright © 2010 DuraSpace. All Rights Reserved.