BASE Development information Overview of the core API Plugin execution

Plugin execution

1. Diagram of classes and methods

The part above the line is the part that the client is using. The lower part are interfaces and classes that mostly are used by the plugin itself and are also part of the net.sf.basedb.core.plugin package.

2. Installing a plugin

A plugin is installed by creating a new PluginDefinition and setting the class name and optioanlly the path to the JAR file. If a JAR file isn't specified the plugin must be on the class path.

When the core installs a new plugin it will try to instantiate it using a default no-argument contructor and cast it to the Plugin interface. If this succeeds it will call the Plugin.getAbout() and Plugin.getMainType() methods and use those values to populate the database with information about the plugin.

If the plugin implements the InteractivePlugin interface the core casts the plugin object and calls the InteractivePlugin.getGuiContexts() method to find out the contexts the plugin cares about.

Finally, the core will check which which PluginType:s it supports simply by checking if the plugin implements any of the registered interfaces.

Note! During the installation of a plugin the Plugin.init() or Plugin.done() methods are not called.

3. Configuring a plugin or job

A client application can configure a PluginConfiguration or Job (if the plugin supports the InteractivePlugin interface). The configuration is started by calling the configure() method on either of those objects. The core returns a PluginConfigurationRequest object which the client uses to find out which parameters are needed by the plugin.

To create the PluginConfigurationRequest object the core has to instantiate a plugin object. Then it creates ParameterValues objects for the configuration and/or job which is passed to the Plugin.init() method. The ParameterValues objects holds the current configuration values.

The client application calls the PluginConfigurationRequest.getRequestInformation() method to get a list of parameters needed by the plugin. This call is simply forwarded to Plugin.getRequestInformation(). When the client application has the list of parameters it should display an interface for the user to enter values for those parameters.

Once the user has entered the values, the client application calls PluginRequest.setParameterValue() method to set the values for the parameters. Then, it is time to call PluginRequest.invoke() which sends the parameters to the plugin by calling the InteractivePlugin.configure() method.

The invoke() method returns a PluginResponse object which is the client applications view of the Response set by the plugin. The response can have three states:

• DONE: The configuration has been completed successfully. The Plugin.done() method is called automatically by the core and if it is a job that we are configuring the estimated execution time is also set. The client application must call PluginResponse.saveParameters() to save all parameter values to the database.
• ERROR: There was an error in the paramerers, use PluginResponse.getErrorList() to get more information. The client application may return to the parameter input screen to allow the user to change the parameters and then call invoke() again.
• CONTINUE: The parameters where ok, but the plugin needs more configuration, use PluginResponse.getNextRequest() to get another PluginConfigurationRequest object. Then repeat the above procedure.

Note! The invoke() method never throws any exceptions, all errors are reported by the PluginResponse.getErrorList().

Note! The client application must keep the PluginConfigurationRequest object itself. This can't be recreated by the core between different requests.

4. Executing a plugin

The execution of a plugin always starts by a client application (or a job queue manager) calling the Job.execute() method. The core creates a PluginExecutionRequest object and instantiates an object of the plugin's class. The Plugin.init() method is called with the job and configuration parameters.

Then, the PluginExecutionRequest.invoke() method is called which is passed on to the Plugin.run() method. The invoke() method returns a PluginResponse object which is the client applications view of the Response object set by the plugin. Before returning the response to the client, the Plugin.done() method is called and the plugin instance is discarded.

The core takes care of updating the job with the status and return (error) messages set by the plugin and also sends a Message to the owning user about the outcome of the execution. This is done by the Job.ProgressReporterImpl class, which also takes care of progress reporting to the database during the execution of the plugin.