Class ExternalProgramExecutor

All Implemented Interfaces:
InteractivePlugin, Plugin, SignalTarget

public class ExternalProgramExecutor
extends AbstractAnalysisPlugin
implements InteractivePlugin, SignalTarget
Since:
2.15
Author:
martin, nicklas
Last modified
$Date: 2019-02-26 11:10:15 +0100 (tis, 26 feb. 2019) $
  • Field Details

    • 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
    • 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 Details

    • ExternalProgramExecutor

      public ExternalProgramExecutor()
  • Method Details

    • 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/derived bioassay and that the logged in user has permission to use the current item.
      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 valid item, 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