How to develop an EDNA plugin

From EdnaWiki
Jump to: navigation, search

This page is an entry point for the documentation around the EDNA plugins. It's a starting point, many important development aspects have not yet been covered:

  • Versioning
  • Compatible versions
  • etc

What is an EDNA plugin?

An EDNA plugin is a Python class derived from one of the EDNA kernel plugin base classes:

Base class Description
EDPlugin The base class of all EDNA plugins.
EDPluginExec The base class of EDNA plugins which does some kind of execution, either an internal calculation or execution of an external process.
EDPluginExecProcess The base class for plugins which executes external processes.
EDPluginExecProcessScript The base class for plugins which executes external processes in scripts. All the current third-party plugins are extended from this class.
EDPluginControl The base class of plugins that control other plugins, either control and/or execution plugins.

The plugin must implement the following methods:

Method name Description
setDataInput A method which accepts either an XML string or an XSDataInput object (see Data_Models for examples of XSDataInput objects). The plugin must override this method in order to implement the conversion between an XML string and its corresponding XSData object.
generateExecutiveSummary This method is called at the end of the execution of the plugin. It should produce an executive summary (i.e. consice and human readable) of the execution and the results of the plugin by calls to the addExecutiveSummaryLine method.

The plugin can override the following methods (strongly recommended but not obligatory):

Method name Description
checkParameters This is the first method to be called. It is used for assuring that the input data to the plugin is complete.
configure This method is called after checkParameters and before execution of the preprocess. If the plugin needs to be configured with data from the configuration file (for example path to an executable) the code for retrieving the data should be implemented in this method.
preProcess This method is called before the process method and should be used for preparing the execution of the plugin, for example preparing input files to external programs.
process This method should not be overidden by plugins inherited from EDPluginExecProcess. For other plugins, this is where the execution of the plugin main task should take place. For control plugins, the workflow should be defined in this method.
postProcess Here should take place any post processing of the results after the process method execution, for example retrieval of data from output files of external programs. The last thing the plugin should do in the postProcess is to call setDataOutput with a XSDataResults object.

More in the pydoc:

Developing an EDNA plugin : Starting points

The are a couple of important points one should do before starting to write a plugin:

Define an Use Case

It is very important to clearly define what the plugin should do and how it should behave in case of errors in a Use Case (see EDNA Use Cases for examples).

Define the type of plugin

Is it a control or an execution plugin? Should it execute an external process in a script?

Define the data input and output

There are two main cases:

Using a specific data model

The only restrictions on the data model is that the input and output objects should be derived from the generic data model classes XSDataInput and XSDataResult.

Using the generic data model

  • If there exists XSDataInput and XSDataResult objects which can be reused, for example XSDataInputIndexing (currently named XSDataIndexingInput but should be renamed) in the XSDataCharacterisationv01 data model, no further work needs to be done.
  • If a new XSDataInput object needs to be created in the generic data model this must be done in concertation with the EDNA project manager and the other EDNA developers. This is probably one of the most difficult scenarios when writing a plugin, it can be avoided by either re-using an existing definition or implementing a specific data model as outlined above.

Developing the plugin - general guide lines

If everything is ready (Use Case and data model), the plugin can start to be coded. Please respect the EDNA coding convention. These are the main steps in coding the plugin:

  1. Create a plugin home directory in the EDNA_HOME/prototype/plugins directory, for example EDNA_HOME/prototype/plugins/EDPluginMyFirstOne-v0.1.
  2. In the plugin base directory create the following directories:
    • plugins: This is were the source code of the plugin will be located.
    • tests: This directory should contain two sub directories:
      • data: This is were the plugin test data should be stored.
      • testsuite: This directory will contain the plugin test cases and test suites.
    • datamodel: Only needed if the plugin implements a specific datamodel.
  3. Start by writing the test cases
  4. Then write the plugin! :)

Developing the plugin - tutorials

It is difficult to give generic instructions on how to write the EDNA plugin, therefore we have put together a tutorial:

  • Here are some information on how we solved some specific issues like data propagation and error handling in the EDNA prototype:
    • Data propagation - generic/specific data models translation : The EDPluginControl is responsible for the EDPluginExec plugins workflow (defined in the process method). As a matter of fact, it is also responsible for the data propagation between EDPluginExec plugins. We generally define transitions methods that (i.e for 2 EDPluginExec plugins sequential execution)
      • retrieves the data output of the first plugin
      • translates into the generic data model via EDHandler classes (if needed)
      • generates data input of the second plugin from the generic data model via EDHandler classes
      • sets the data input to the second plugin
      • executes the second plugin
    • Error/warning Handling:
      • The EDPluginControl defines the success/failure workflow of the EDPluginExec plugins in its process method.
      • If expected fatal errors (like file not found, etc...) occured in a EDPluginExec plugin, this latter creates an error message (using the EDMessage class), adds it in its error message list and raise a RuntimeError bundled with the error message. The EDPluginControl then calls the method associated with the connectFAILURE slot and retrieves the EDPluginExec plugin messages with the method self.retrieveFailureMessages (this method checks also for unexpected errors).
      • For non fatal cases, the EDPluginExec plugin simply adds warning or error messages to its messages list without raising any exceptions. In such cases, the EDPluginControl calls the method associated to the connectSUCCESS slot and retrieves the EDPluginExec plugin message by using self.retrieveSuccessMessages