net.sf.basedb.plugins.executor
Class ExternalProgramExecutor

java.lang.Object
  net.sf.basedb.core.plugin.AbstractPlugin
      net.sf.basedb.core.plugin.AbstractAnalysisPlugin
          net.sf.basedb.plugins.executor.ExternalProgramExecutor

All Implemented Interfaces:

InteractivePlugin, Plugin, SignalTarget

public class ExternalProgramExecutor
extends AbstractAnalysisPlugin
implements InteractivePlugin, SignalTarget

Since:

2.15

Author:

martin, nicklas

Last modified

$Date: 2011-02-18 13:19:38 +0100 (Fri, 18 Feb 2011) $

Nested Class Summary

(package private) static class	ExternalProgramExecutor.RequestWrapper
(package private) static class	ExternalProgramExecutor.ResponseWrapper

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

Plugin.MainType

Field Summary

private static About	about
private static String	COMMAND_CONFIGURE_EXTERNAL_PARAMETERS
private RequestInformation	configureExportImportPluginParameters
private RequestInformation	configureExternalParameters
private RequestInformation	configureJob
private RequestInformation	configurePlugin
private IOSupport	exporter
private IOSupport	importer
private Set<File>	knownFiles Files that are known to exists in the working directory.
static String	NAMESPACE_EXPORTER The namespace for the exporter plug-in parameters.
static String	NAMESPACE_EXTERNAL The namespace for the external program parameters.
static String	NAMESPACE_IMPORTER The namespace for the importer plug-in parameters.
static String	PARAMETER_DEBUG_MODE Parameter name for debug mode flag.
static String	PARAMETER_EXPORTER_CLASS Parameter name for the class that has been selected as the exporter.
static String	PARAMETER_EXTERNAL_CMDLINE Parameter name for the command line options to the external program.
static String	PARAMETER_EXTERNAL_PARAMETERS Parameter name for the xml holding the parameter definitions to the external program.
static String	PARAMETER_EXTERNAL_PATH Parameter name for the path to the external program.
static String	PARAMETER_IMPORTER_CLASS Parameter name for the class that has been selected as the importer.
static String	PARAMETER_NUM_CHANNELS Parameter name for the required number of channels.
static String	PARAMETER_RAW_DATA_TYPE Parameter name for the required raw data type.
static String	PARAMETER_SOURCE_BIOASSSAYSET Parameter name for the source bioassay set.
static String	PARAMETER_SOURCE_TRANSFORM Parameter name for the required intensity transform of the source bioassay set.
private ThreadSignalHandler	signalHandler
private File	workDir Temporary working directory at runtime.

Fields inherited from class net.sf.basedb.core.plugin.AbstractAnalysisPlugin

CHILD_DESCRIPTION, CHILD_NAME, CONTEXT_BIOASSAYS, CONTEXT_BIOASSAYSET, defaultGuiContexts, nameType, optionalNameType, SOURCE_BIOASSAYS, SOURCE_BIOASSAYSET, TRANSFORMATION_NAME

Fields inherited from class net.sf.basedb.core.plugin.AbstractPlugin

annotationSection, configuration, COPY_ANNOTATIONS, job, OVERWRITE_ANNOTATIONS, sc

Constructor Summary

ExternalProgramExecutor()

Method Summary

private void	addParametersWithNamespace(List<PluginParameter<?>> to, List<PluginParameter<?>> from, String namespace) Add more parameters to a list of parameters with a different namespace.
void	configure(GuiContext context, Request request, Response response) Configure the plugin.
File	createFile(String name) Create a new file in the working directory.
protected IOSupport	createInstance(DbControl dc, PluginDefinition plugin, String namespace, boolean runtime) Create and initialize a plug-in instance for the given plug-in definition.
protected File	createTemporaryWorkingDirectory() Create a temporary working directory in the local file system.
About	getAbout() Get information about the plugin, such as name, version, authors, etc.
private RequestInformation	getConfigureExportImportPluginParameters()
private RequestInformation	getConfigureExternalParameters()
private RequestInformation	getConfigureJobParameters()
private RequestInformation	getConfigurePluginParameters()
BioAssaySet	getCurrentBioAssaySet(DbControl dc) Get the bioassay set that is used as the source for the job.
private List<PluginParameter<?>>	getExernalPluginParameters(DbControl dc, BioAssaySet source)
protected IOSupport	getExporter(DbControl dc, boolean forceNew, boolean runtime) Get an instance of the exporter plug-in.
protected IOSupport	getImporter(DbControl dc, boolean forceNew, boolean runtime) Get an instance of the importer plug-in.
List<ParameterDefinition>	getParameterDefinitions(boolean validate) Get the current program parameter definitions.
List<ProgramParameter>	getProgramParameters() Get all program parameters and their values.
RequestInformation	getRequestInformation(GuiContext context, String command) This method will return the RequestInformation for a given command, i.e.
SignalHandler	getSignalHandler() Get the signal handler that is handling signals on behalf of this object.
File	getWorkingDirectory() Get the current working directory were data files for the external program are stored.
List<File>	inspectWorkingDirectory() Check the working directory for new files.
String	isInContext(GuiContext context, Object item) Check that the item is a bioassayset and that the logged in user has permission to use the current experiment.
boolean	requiresConfiguration() Returns FALSE, since that is how the plugins used to work before this method was introduced.
void	run(Request request, Response response, ProgressReporter progress) Run the plugin.
protected void	runExporter(Request request, Response response, ProgressReporter progress) Execute the exporter plug-in using the supplied parameters.
protected void	runExternalProgram(String program, String cmdLine, File workDir, String stdin, String stdout, ProgressReporter progress) Run the external program.
protected void	runImporter(Request request, Response response, ProgressReporter progress) Execute the importer plug-in using the supplied parameters.
boolean	supportsConfigurations() Returns TRUE, since that is how the plugins used to work before this method was introduced.

Methods inherited from class net.sf.basedb.core.plugin.AbstractAnalysisPlugin

getChildDescriptionParameter, getChildNameParameter, getCurrentExperiment, getGuiContexts, getMainType, getSourceBioAssays, getSourceBioAssaySet, getSourceBioAssaySetParameter, getSourceBioAssaysParameter, getTransformationName, getTransformationNameParameter, restrictSource

Methods inherited from class net.sf.basedb.core.plugin.AbstractPlugin

checkInterrupted, cloneParameterWithDefaultValue, closeLogFile, createLogFile, done, getCopyAnnotationsParmeter, getCurrentConfiguration, getCurrentJob, getJobOrConfigurationValue, getOverwriteAnnotationsParameters, getPermissions, init, log, log, storeValue, storeValue, storeValues, validateRequestParameters

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.InteractivePlugin

getGuiContexts

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

done, getMainType, getPermissions, init

Field Detail

PARAMETER_EXTERNAL_PATH

public static final String PARAMETER_EXTERNAL_PATH

Parameter name for the path to the external program. This parameter is a String parameter stored in the plug-in configuration.

See Also:

Constant Field Values

PARAMETER_EXTERNAL_CMDLINE

public static final String PARAMETER_EXTERNAL_CMDLINE

Parameter name for the command line options to the external program. This parameter is a String parameter stored in the plug-in configuration.

See Also:

Constant Field Values

PARAMETER_EXTERNAL_PARAMETERS

public static final String PARAMETER_EXTERNAL_PARAMETERS

Parameter name for the xml holding the parameter definitions to the external program. This parameter is an XML String stored in the plug-in configuration.

See Also:

Constant Field Values

PARAMETER_IMPORTER_CLASS

public static final String PARAMETER_IMPORTER_CLASS

Parameter name for the class that has been selected as the importer. This parameter is a String parameter stored in the plug-in configuration.

See Also:

Constant Field Values

PARAMETER_EXPORTER_CLASS

public static final String PARAMETER_EXPORTER_CLASS

Parameter name for the class that has been selected as the exporter. This parameter is a String parameter stored in the plug-in configuration.

See Also:

Constant Field Values

PARAMETER_DEBUG_MODE

public static final String PARAMETER_DEBUG_MODE

Parameter name for debug mode flag.

See Also:

Constant Field Values

PARAMETER_RAW_DATA_TYPE

public static final String PARAMETER_RAW_DATA_TYPE

Parameter name for the required raw data type. This parameter is a String parameter stored in the plug-in configuration.

See Also:

Constant Field Values

PARAMETER_NUM_CHANNELS

public static final String PARAMETER_NUM_CHANNELS

Parameter name for the required number of channels. This parameter is an Integer parameter stored in the plug-in configuration.

See Also:

Constant Field Values

PARAMETER_SOURCE_TRANSFORM

public static final String PARAMETER_SOURCE_TRANSFORM

Parameter name for the required intensity transform of the source bioassay set. This parameter is a String parameter (corresponding to Enum.name()) stored in the plug-in configuration.

See Also:

Constant Field Values

PARAMETER_SOURCE_BIOASSSAYSET

public static final String PARAMETER_SOURCE_BIOASSSAYSET

Parameter name for the source bioassay set. This parameter is a BioAssaySet parameter stored in the job configuration.

See Also:

Constant Field Values

NAMESPACE_EXPORTER

public static final String NAMESPACE_EXPORTER

The namespace for the exporter plug-in parameters.

See Also:

Constant Field Values

NAMESPACE_IMPORTER

public static final String NAMESPACE_IMPORTER

The namespace for the importer plug-in parameters.

See Also:

Constant Field Values

NAMESPACE_EXTERNAL

public static final String NAMESPACE_EXTERNAL

The namespace for the external program parameters.

See Also:

Constant Field Values

about

private static final About about

COMMAND_CONFIGURE_EXTERNAL_PARAMETERS

private static final String COMMAND_CONFIGURE_EXTERNAL_PARAMETERS

See Also:

Constant Field Values

signalHandler

private ThreadSignalHandler signalHandler

configurePlugin

private RequestInformation configurePlugin

configureExternalParameters

private RequestInformation configureExternalParameters

configureJob

private RequestInformation configureJob

configureExportImportPluginParameters

private RequestInformation configureExportImportPluginParameters

workDir

private File workDir

Temporary working directory at runtime.

knownFiles

private Set<File> knownFiles

Files that are known to exists in the working directory. Unknown files can be assumed to have been created by the external program.

exporter

private IOSupport exporter

importer

private IOSupport importer

Constructor Detail

ExternalProgramExecutor

public ExternalProgramExecutor()

Method Detail

getAbout

public About getAbout()

Description copied from interface: Plugin

Get information about the plugin, such as name, version, authors, etc.

Specified by:

getAbout in interface Plugin

Returns:

An About object

supportsConfigurations

public boolean supportsConfigurations()

Description copied from class: AbstractPlugin

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

Specified by:

supportsConfigurations in interface Plugin

Overrides:

supportsConfigurations in class AbstractPlugin

Returns:

TRUE or FALSE

requiresConfiguration

public boolean requiresConfiguration()

Description copied from class: AbstractPlugin

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

Specified by:

requiresConfiguration in interface Plugin

Overrides:

requiresConfiguration in class AbstractPlugin

Returns:

TRUE or FALSE

run

public void run(Request request,
                Response response,
                ProgressReporter progress)

Description copied from interface: Plugin

Run the plugin. If a progress reporter object is passed it is recommended that the plugin makes use of it.

Specified by:

run in interface Plugin

Parameters:

request - Request object with the command and parameters

response - Response object in for the plugin to response through

progress - A ProgressReporter where the plugin can report its progess, can be null

getSignalHandler

public SignalHandler getSignalHandler()

Description copied from interface: SignalTarget

Get the signal handler that is handling signals on behalf of this object. Multiple invokations of this method may receive the same or different objects. Null may be returned if, for some reason, the current object instance doesn't want to receive signals. Returning null is the same as not implementing this interface.

Specified by:

getSignalHandler in interface SignalTarget

Returns:

A SignalHandler object, or null if the current instance doesn't support signals

isInContext

public String isInContext(GuiContext context,
                          Object item)

Description copied from class: AbstractAnalysisPlugin

Check that the item is a bioassayset and that the logged in user has permission to use the current experiment.

Specified by:

isInContext in interface InteractivePlugin

Overrides:

isInContext in class AbstractAnalysisPlugin

Parameters:

context - Current guicontext

item - The item to check.

Returns:

null if the item is a bioassayset, an error message otherwise

getRequestInformation

public RequestInformation getRequestInformation(GuiContext context,
                                                String command)
                                         throws BaseException

Description copied from interface: InteractivePlugin

This method will return the RequestInformation for a given command, i.e. the list of parameters and some nice help text.

Specified by:

getRequestInformation in interface InteractivePlugin

Parameters:

context - The current context of the client application, it is one of the values found in set returned by InteractivePlugin.getGuiContexts()

command - The command

Returns:

The RequestInformation for the command

Throws:

BaseException - if there is an error

configure

public void configure(GuiContext context,
                      Request request,
                      Response response)

Description copied from interface: InteractivePlugin

Configure the plugin. Hopefully the client is supplying values for the parameters specified by InteractivePlugin.getRequestInformation(GuiContext, String).

Specified by:

configure in interface InteractivePlugin

Parameters:

context - The current context of the client application, it is one of the values found in set returned by InteractivePlugin.getGuiContexts()

request - Request object with the command and parameters

response - Response object in for the plugin to response through

getCurrentBioAssaySet

public BioAssaySet getCurrentBioAssaySet(DbControl dc)

Get the bioassay set that is used as the source for the job. This method should only be called at runtime or job configuration time.

Overrides:

getCurrentBioAssaySet in class AbstractAnalysisPlugin

Parameters:

dc - The DbControl to use for database access

Returns:

The source bioassay set

See Also:

AbstractAnalysisPlugin.getSourceBioAssaySet(DbControl)

getWorkingDirectory

public File getWorkingDirectory()

Get the current working directory were data files for the external program are stored. This method should only be called at runtime.

inspectWorkingDirectory

public List<File> inspectWorkingDirectory()

Check the working directory for new files. Each call to this method will mark the existing files as "known" files. Subsequent calls will only find files that has been added to the working directory since that last call. The executor calls this method after the exporter plug-in has been executed just before the external program is about to be started. This allows the importer plug-in to call this method to find out which files that were created by the external program.

Returns:

A list with new files that has been added to the working directory since the last call (the list is empty if no new files exists)

Since:

2.16

getParameterDefinitions

public List<ParameterDefinition> getParameterDefinitions(boolean validate)

Get the current program parameter definitions. This method should only be called at runtime or job configuration time.

getProgramParameters

public List<ProgramParameter> getProgramParameters()

Get all program parameters and their values. This method should only be called at runtime.

createFile

public File createFile(String name)
                throws IOException

Create a new file in the working directory. If a file with the given name already exists the existing file is used.

Parameters:

name - The name of the file to create

Returns:

A new file object pointing to the file

Throws:

IOException

createTemporaryWorkingDirectory

protected File createTemporaryWorkingDirectory()
                                        throws IOException

Create a temporary working directory in the local file system. The exporter should export data to this directory. The external program will use the data and store it's output in the same directory. It is recommended that the directory is empty and not used by any other process at the same time. Existing files may be overwritten without notice.

Returns:

A file object representing a directory

Throws:

IOException

runExporter

protected void runExporter(Request request,
                           Response response,
                           ProgressReporter progress)

Execute the exporter plug-in using the supplied parameters.

runImporter

protected void runImporter(Request request,
                           Response response,
                           ProgressReporter progress)

Execute the importer plug-in using the supplied parameters.

runExternalProgram

protected void runExternalProgram(String program,
                                  String cmdLine,
                                  File workDir,
                                  String stdin,
                                  String stdout,
                                  ProgressReporter progress)

Run the external program. The program and active working directory is given by the parameters. No command line options can be sent to the program. It is possible to name one (existing) file that should be piped to standard input to the plug-in and one (non-existing) file that should receive output from the program. Anything the program writes to the standard error stream should cause an error and be reported back to the caller via en exception.

Parameters:

program - The path to the external program

workDir - The active working directory

stdin - If given, the named file within the working directory should be piped to the standard input of the external program.

stdout - If given, output from the external program should be piped the named file. If not given any output from the program needs to be read and discarded

getExporter

protected IOSupport getExporter(DbControl dc,
                                boolean forceNew,
                                boolean runtime)

Get an instance of the exporter plug-in.

Parameters:

dc - A DbControl to use for database access

forceNew - If TRUE a new instance must always be created, otherwise an already existing instance may be re-used

runtime - TRUE if the importer is created at runtime, which means that job agent configuration must be taking into account

Returns:

An exporter instance

getImporter

protected IOSupport getImporter(DbControl dc,
                                boolean forceNew,
                                boolean runtime)

Get an instance of the importer plug-in.

Parameters:

dc - A DbControl to use for database access

forceNew - If TRUE a new instance must always be created, otherwise an already existing instance may be re-used

runtime - TRUE if the importer is created at runtime, which means that job agent configuration must be taking into account

Returns:

An importer instance

createInstance

protected IOSupport createInstance(DbControl dc,
                                   PluginDefinition plugin,
                                   String namespace,
                                   boolean runtime)

Create and initialize a plug-in instance for the given plug-in definition. Job and configuration parameters should be wrapped in the given namespace.

Parameters:

plugin - The plug-in definition we should instantiate

namespace - The namespace, or null to not wrap the parameters in a namespace

runtime - TRUE if the importer is created at runtime, which means that job agent configuration must be taking into account

Returns:

An initialized plug-in instance

getConfigurePluginParameters

private RequestInformation getConfigurePluginParameters()

getConfigureExportImportPluginParameters

private RequestInformation getConfigureExportImportPluginParameters()

getConfigureExternalParameters

private RequestInformation getConfigureExternalParameters()

getConfigureJobParameters

private RequestInformation getConfigureJobParameters()

getExernalPluginParameters

private List<PluginParameter<?>> getExernalPluginParameters(DbControl dc,
                                                            BioAssaySet source)

addParametersWithNamespace

private void addParametersWithNamespace(List<PluginParameter<?>> to,
                                        List<PluginParameter<?>> from,
                                        String namespace)

Add more parameters to a list of parameters with a different namespace.

Parameters:

to - The parameters list to add the parameters to

from - The parameters list to copy parameters from

namespace - The namespace to use for the added parameter