Plugins.md

# Task Plugins #

The *Task* entities defined in a *Processor* definition can be implemented as dedicated native java plugins or as scripts written in *Perl*, *Python* or *Shell* scripting languages.


## Native plugins ##

Dedicated native java plugins can be developed by implementing the GenericTaskInterface process method defined in the DES library

**GenericTaskInterface Interface**

```java
public interface GenericTaskInterface {

	/**
	 * 
	 * @param basepath Basepath as configured in DistributionServer.ini
	 * @param aoi_name AOI name contained in the $processor.processor_config.xml
	 * @param processor_name Processor name related to the $processor.processor_config.xml
	 * @param entity_name Name of executing entity (Task, Consumer, etc.)
	 * @param parameters Parameters as defined by <Parameter>
	 * @param args List of arguments of the Task (String or Hashtables, to be checked by the plugin)
	 * @param files List of files of the Task IFF <FileType>regexp</FileType> is defined, else null
	 * @return ExitCodes
	 */
	public int process(String basepath, String aoi_name,
			String processor_name, String entity_name, Hashtable parameters, Object[] args, String[] files);
	
}
```

The implemented plugin should be packaged as a jar file and placed in the DES ./plugins directory where it is automatically loaded at Runtime.

The plugin can be executed in a given *Processor* *Task* with the following definition:

Example:
```xml
<Task name="renameFiles" type="class" active="yes" priority="NORM">
	<Command>class</Command>
	<FileType>SAMPLE.*.AA.txt</FileType>
	<Parameter>edu.eurac.distributionserver.tasks.generic.FileRename</Parameter>
	<FilePrefix>RENAME</FilePrefix>
</Task>
```

The parameters can be passed to the *Task* plugin with one of the following options:
    
- By using a custom keyword tag eg. *FilePrefix* in the *Task* definition and then accessing the parameter with the Hashtable parameters in the Interface
    
```java
    String file_prefix = (String)parameters.get("FilePrefix");
```
    
- By using the *Parameter* tag in the *Task* definition and than referencing the parameter with the Object[] args type in the Interface
    
```java
    String classname = (String)args[1];
```
Note: Note: args[0] is the class name
 
 
 
## Script plugins ##
 
 
If a given *Task* is implemented with a scripting language (*Perl*, *Python*, *Shell*), the script must consider the following input parameters:
 
```
[BASE_PATH] [AOI] [PROCESSOR] [Parameter_1] [Parameter_N] ... [$FILE*]
```
 
IFF a *FileType* filtering is defined for the *Task*, the last parameter, defined above as $FILE, is the filename of the 1st file filtered by the Task execution.
In this case the script will be executed N times, for each file filtered by the FileType regular expression.
 
 
Example:
```perl
#!/usr/bin/perl -w

# This script is part of the Task plugin collection available for the DES (Data Exchange Server)
# version: 1.0
# usage: testPerlExitCode.pl [base_path] [aoi] [procesosr_name] [Sleep] [ExitCodeToReturn]

#main
print "running testPerlExitCode.pl\n";
my $base_path = "null";
my $aoi = "null";
my $processor_name = "null";
my $sleep_sec = 1; # 1 second default 
my $exit_code = -1;
print "Parameters: @ARGV\n";
if(scalar(@ARGV) < 4){
	print "missing arguments!\n";
	print "usage: testPerlExitCode.pl [base_path] [aoi] [Sleep] [ExitCode]\n";
	exit -1;
}else{
	$base_path = $ARGV[0];
	$aoi = $ARGV[1];
	$processor_name = $ARGV[2];
	$sleep_sec = $ARGV[3];
	$exit_code = $ARGV[4];
	print "base_path: $base_path, aoi: $aoi, processor_name: $processor_name, Sleep: $sleep_sec , ExitCode: $exit_code\n";
	print "sleep $sleep_sec seconds...\n";
	sleep $sleep_sec;
	exit $exit_code;
}
```

The *Task* definition for the script above is:
```xml
<Task name="testExitCode" type="cmd" active="yes" priority="NORM">
	<EMail>mail@host.yourdomain</EMail>
	<NotifyEmail>OnError</NotifyEmail>
	<Command>perl</Command>
	<Parameter>./test_data/scripts/testPerlExitCode.pl</Parameter>
	<Parameter>@mySleep</Parameter>
	<Parameter>@myExitCode</Parameter>
</Task>
```