net.sf.basedb.core.plugin
Class AbstractPlugin

java.lang.Object
  net.sf.basedb.core.plugin.AbstractPlugin

All Implemented Interfaces:

Plugin

Direct Known Subclasses:

AbstractAnalysisPlugin, AbstractExporterPlugin, AbstractFileUnpacker, AbstractFlatFileImporter, AbstractIOSupport, BfsExporterPlugin, CdfFileReporterImporter, HelpImporter, IntensityCalculatorPlugin, PluginConfigurationImporter, SpotImageCreator

public abstract class AbstractPlugin
extends Object
implements Plugin

This is an abstract base class useful for developing plugins. It's main purpose is to help with validating and storing request parameters into the plugin or job configuration.

Version:

2.0

Author:

Enell, Nicklas

Last modified

$Date: 2010-09-10 13:09:05 +0200 (Fri, 10 Sep 2010) $

Nested Class Summary

Nested classes/interfaces inherited from interface net.sf.basedb.core.plugin.Plugin

Plugin.MainType

Field Summary

protected static PluginParameter<String>	annotationSection Section definition for grouping annotation options.
protected ParameterValues	configuration
protected static String	COPY_ANNOTATIONS The name of the parameter that asks if annotations should be copied or not.
protected ParameterValues	job
private DbControl	logDc
private File	logfile
private PrintWriter	logger
protected static String	OVERWRITE_ANNOTATIONS The name of the parameter that asks if annotations should be overwritten or not.
protected SessionControl	sc

Constructor Summary

protected

AbstractPlugin() Create a new AbstractPlugin.

Method Summary

protected void	checkInterrupted() Deprecated. In 2.16, use ThreadSignalHandler.checkInterrupted() instead
protected <T> PluginParameter<T>	cloneParameterWithDefaultValue(PluginParameter<T> pp) Clone a plug-in parameter and set the default value to the value that is already stored in the job or configuration parameters.
protected void	closeLogFile() Close the log file created by createLogFile(String).
protected void	createLogFile(String path) Create a log file in the BASE file system for logging detailed information from a plug-in.
void	done() Clears the variables set by the init method.
protected PluginParameter<Boolean>	getCopyAnnotationsParmeter(String label, String description, Boolean defaultValue) Parameter definition that asks if annotations should be copied from the plug-in definition/configuration to other items.
protected PluginConfiguration	getCurrentConfiguration(DbControl dc) Get the plug-in configuration that this is currently in use or null.
protected Job	getCurrentJob(DbControl dc) Get the job that is executing this plugin or null.
protected Object	getJobOrConfigurationValue(String name) Get the value for a job or configuration parameter.
protected PluginParameter<Boolean>	getOverwriteAnnotationsParameters(String label, String description, Boolean defaultValue) Parameter definition that asks if copied annotations should overwrite existing annotations or not.
Collection<Permissions>	getPermissions() Return null, which gives the plugin the same permissions as the logged in user.
void	init(SessionControl sc, ParameterValues configuration, ParameterValues job) Store copies of the session control, plugin and job configuration.
protected void	log(String message) Log a message to the log file created by createLogFile(String).
protected void	log(String message, Throwable t) Log a message and stack trace to the log file created by createLogFile(String).
boolean	requiresConfiguration() Returns FALSE, since that is how the plugins used to work before this method was introduced.
protected <T> void	storeValue(ParameterValues values, PluginParameter<T> parameter, T value) Store a value in a ParameterValues object.
protected <T> void	storeValue(ParameterValues values, Request request, PluginParameter<T> parameter) Copy a parameter value from a Request to a ParameterValues object.
protected <T> void	storeValues(ParameterValues values, Request request, PluginParameter<T> parameter) Copy a list of parameter values from a Request to a ParameterValues object.
boolean	supportsConfigurations() Returns TRUE, since that is how the plugins used to work before this method was introduced.
protected List<Throwable>	validateRequestParameters(List<PluginParameter<?>> parameters, Request request) Validate the parameter values in a request against a list of plugin parameter definitions.

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.basedb.core.plugin.Plugin

getAbout, getMainType, run

Field Detail

sc

protected SessionControl sc

configuration

protected ParameterValues configuration

job

protected ParameterValues job

logDc

private DbControl logDc

logfile

private File logfile

logger

private PrintWriter logger

annotationSection

protected static final PluginParameter<String> annotationSection

Section definition for grouping annotation options.

Since:

2.5

COPY_ANNOTATIONS

protected static final String COPY_ANNOTATIONS

The name of the parameter that asks if annotations should be copied or not.

Since:

2.5

See Also:

getCopyAnnotationsParmeter(String, String, Boolean), Constant Field Values

OVERWRITE_ANNOTATIONS

protected static final String OVERWRITE_ANNOTATIONS

The name of the parameter that asks if annotations should be overwritten or not.

Since:

2.5

See Also:

getOverwriteAnnotationsParameters(String, String, Boolean), Constant Field Values

Constructor Detail

AbstractPlugin

protected AbstractPlugin()

Create a new AbstractPlugin.

Method Detail

init

public void init(SessionControl sc,
                 ParameterValues configuration,
                 ParameterValues job)
          throws BaseException

Store copies of the session control, plugin and job configuration. These are available to subclasses in the sc, configuration and job variables. If a subclass overrides this method it is recommended that it also calls super.init(sc, configuration, job).

Specified by:

init in interface Plugin

Parameters:

sc - A SessionControl object that the plugin can use to communicate with the core.

configuration - The configuration parameters for the plugin

job - The job parameters for the plugin

Throws:

BaseException - if there is an error.

done

public void done()

Clears the variables set by the init method. If a subclass overrides this method it is recommended that it also calls super.done().

Specified by:

done in interface Plugin

supportsConfigurations

public boolean supportsConfigurations()

Returns TRUE, since that is how the plugins used to work before this method was introduced.

Specified by:

supportsConfigurations in interface Plugin

Returns:

TRUE or FALSE

requiresConfiguration

public boolean requiresConfiguration()

Returns FALSE, since that is how the plugins used to work before this method was introduced.

Specified by:

requiresConfiguration in interface Plugin

Returns:

TRUE or FALSE

getPermissions

public Collection<Permissions> getPermissions()

Return null, which gives the plugin the same permissions as the logged in user.

Specified by:

getPermissions in interface Plugin

Returns:

A collection of permissions or null to not use permissions

validateRequestParameters

protected List<Throwable> validateRequestParameters(List<PluginParameter<?>> parameters,
                                                    Request request)

Validate the parameter values in a request against a list of plugin parameter definitions. The validation is done by calling the ParameterType.validate(String, List) for each parameter in the list of parameter definitions. If all parameters are valid this method returns null, otherwise a list of exceptions that ocurred during the validation. This list can be directly propagated to the Response.setError(String, List) method. For example:

// In Plugin.invoke() method:
List<PluginParameter<?>> parameters = getParametersForCommand(request.getCommand());
List<Throwable> errors = 
   validateRequestParameters(parameters, request);
if (errors != null)
{
   response.setError(errors.size()+
      " invalid parameter(s) were found in the request", errors);
   return;
}

Parameters:

parameters - A list containing the parameter definitions

request - The request

Returns:

A list of exceptions, or null if all parameters are valid

storeValue

protected <T> void storeValue(ParameterValues values,
                              Request request,
                              PluginParameter<T> parameter)
                   throws BaseException

Copy a parameter value from a Request to a ParameterValues object. This method makes it easy for a subclass to directly store a request parameter into either the plugin or job configuration. Use this method when the parameter valus is a single value.

Parameters:

values - The ParameterValues object where the value should be stored, use either configuration or job

request - The Request object

parameter - The PluginParameter object for the parameter

Throws:

BaseException - If the parameter value is invalid

storeValue

protected <T> void storeValue(ParameterValues values,
                              PluginParameter<T> parameter,
                              T value)

Store a value in a ParameterValues object. This method is useful when a plugin needs to store a value that is not part of the request.

Type Parameters:

T - The type of the parameter

Parameters:

values - The ParameterValues object where the value should be stored, use either configuration or job

parameter - The PluginParameter object for the parameter

value - The value to save

Throws:

BaseException - If the parameter value is invalid

storeValues

protected <T> void storeValues(ParameterValues values,
                               Request request,
                               PluginParameter<T> parameter)
                    throws BaseException

Copy a list of parameter values from a Request to a ParameterValues object. This method makes it easy for a subclass to directly store a request parameter into either the plugin or job configuration. Use this method when the parameter value is a list of values.

Parameters:

values - The ParameterValues object where the value should be stored, use either configuration or job

request - The Request object

parameter - The ParameterType object for the parameter

Throws:

BaseException - If the parameter value is invalid

getCurrentJob

protected Job getCurrentJob(DbControl dc)

Get the job that is executing this plugin or null.

Parameters:

dc - The DbControl to use for database access

Returns:

The job or null

getCurrentConfiguration

protected PluginConfiguration getCurrentConfiguration(DbControl dc)

Get the plug-in configuration that this is currently in use or null.

Parameters:

dc - The DbControl to use for database access

Returns:

The configuration or null

Since:

2.5

getCopyAnnotationsParmeter

protected PluginParameter<Boolean> getCopyAnnotationsParmeter(String label,
                                                              String description,
                                                              Boolean defaultValue)

Parameter definition that asks if annotations should be copied from the plug-in definition/configuration to other items.

Parameters:

label - The label to use for the parameter or null to use the default label (Copy annotations)

description - The description to use for the parameter or null to use the default description

defaultValue - The default value

getOverwriteAnnotationsParameters

protected PluginParameter<Boolean> getOverwriteAnnotationsParameters(String label,
                                                                     String description,
                                                                     Boolean defaultValue)

Parameter definition that asks if copied annotations should overwrite existing annotations or not.

Parameters:

label - The label to use for the parameter or null to use the default label (Overwrite existing)

description - The description to use for the parameter or null to use the default description

defaultValue - The default value

Since:

2.5

getJobOrConfigurationValue

protected Object getJobOrConfigurationValue(String name)

Get the value for a job or configuration parameter. This method first checks the job parameters. If there is no value it will check the configuration parameters.

Parameters:

name - The name of the parameter

Returns:

The parameter value, or null

Since:

2.15

cloneParameterWithDefaultValue

protected <T> PluginParameter<T> cloneParameterWithDefaultValue(PluginParameter<T> pp)

Clone a plug-in parameter and set the default value to the value that is already stored in the job or configuration parameters.

Parameters:

pp - The parameter to clone

Returns:

The cloned parameter

Since:

2.15

checkInterrupted

@Deprecated
protected void checkInterrupted()

Deprecated. In 2.16, use ThreadSignalHandler.checkInterrupted() instead

Check if the current thread has been interrupted and throw a SignalException if it has. Subclasses that use the ThreadSignalHandler or EnhancedThreadSignalHandler to implement signal handling should regularly call this method.

Since:

2.6

createLogFile

protected void createLogFile(String path)

Create a log file in the BASE file system for logging detailed information from a plug-in. The log file will be created if it doesn't exists. The log file is handled in it's own transaction. Call closeLogFile() to close the log file and commit changes to the database. If this method is called when a log file is open, it does nothing.

Parameters:

path - The path to log to, if null this method does nothing

Since:

2.8

closeLogFile

protected void closeLogFile()

Close the log file created by createLogFile(String).

Since:

2.8

log

protected void log(String message)

Log a message to the log file created by createLogFile(String). If no log file has been created, this method does nothing.

Parameters:

message - The message to log

Since:

2.8

log

protected void log(String message,
                   Throwable t)

Log a message and stack trace to the log file created by createLogFile(String). If not log file exists, this method does nothing.

Parameters:

message - The message to log

t - A stack trace

Since:

2.8