com.virtuosotechnologies.lib.plugin
Interface PluginInitializer

All Known Implementing Classes:

BasicPluginInitializer, MainGuiPlugin

public interface PluginInitializer

The interface that plugins must implement to perform initialization. Generally, a plugin should perform one-time initialization of the plugin itself in the initialize() method, and initialize the individual API implementations on request in the getAPIImplementation() method. For some plugins, however, the various API implementations may be so intertwined that it makes more sense to initialize them all at once in the initialize() method, and merely return the appropriate already-created object in getAPIImplementation(). In either case, the plugin's PluginInfo should reflect which APIs the initialize() and getAPIImplementation() methods expect to have available in the PluginLinker.

Each plugin has a single PluginLinker object assigned to it, so the same linker object will be passed to initialize() and each invocation of getAPIImplementation().

The methods in this interface should only be called from within a Framework's plug() and unplug() methods. Because those methods are defined to be synchronized and non-reentrant, there should be no need to synchronize implementations of PluginInitializer. However, note that there is no guarantee which thread these methods will be running in.

Method Summary

Object	getAPIImplementation(Class apiClass, PluginLinker linker) A plugin must implement this method to provide the implementations of the APIs that it provides.
void	initialize(PluginLinker linker) Perform first initialization of the plugin.
boolean	preShutDown(PluginLinker linker) Perform any pre-shutdown tasks.
void	shutDown(PluginLinker linker) Perform finalization and shutdown of the plugin.

Method Detail

initialize

public void initialize(PluginLinker linker)
                throws PluginInitializerException

Perform first initialization of the plugin. This is called after the plugin is instantiated, but before it is asked to provide any of its API implementations. Any APIs the plugin declared it needed for initialization will be available through the linker when this method is called.

Plugins should perform any time-consuming initialization in this method, rather than in the constructor or static initializers, and should use this method to report any fatal errors during initialization.

Parameters:

linker - the linker for this plugin.

Throws:

PluginInitializerException - thrown if the plugin could not initialize itself.

getAPIImplementation

public Object getAPIImplementation(Class apiClass,
                                   PluginLinker linker)
                            throws PluginInitializerException

A plugin must implement this method to provide the implementations of the APIs that it provides. This method is called after the initialize() method. Any APIs the plugin declared it needed in to implement this API will be available through the linker when this method is called.

Plugins should perform any time-consuming initialization in this method, rather than in the constructor or static initializers, and should use this method to report any fatal errors during initialization.

Parameters:

apiClass - the class of the API to implement

linker - the linker for this plugin.

Returns:

an object implementing the API.

Throws:

PluginInitializerException - thrown if the plugin could not implement the API.

preShutDown

public boolean preShutDown(PluginLinker linker)

Perform any pre-shutdown tasks. The plugin can also abort shutdown at this point by returning false. Normally, if a plugin must abort shutdown it should do so gracefully in this method rather than throwing an exception out of shutdown(). Note that this method may be called even when the plugin is not actually going to be shutdown. This is because another plugin in the shutdown set may abort the shutdown procedure. In other words, this method may be called any number of times during the course of execution. Therefore, the plugin should not actually shut itself down in this method, but should instead do just enough that it knows it can actually perform a full shutdown if shutdown() is later called.

Parameters:

linker - the linker for this plugin.

Returns:

true if successful, or false if the plugin is aborting shutdown

shutDown

public void shutDown(PluginLinker linker)
              throws PluginInitializerException

Perform finalization and shutdown of the plugin. This is called when the plugin is being unplugged.

Parameters:

linker - the linker for this plugin.

Throws:

PluginInitializerException - thrown if the plugin could not shut down.