Developing GFAC Plugins

This document will explain how to use GFAC Handler framework to extend the GFAC functionality. In this tutorial we will demonstrate how to write your own handler, install the handler to Apache Airavata runtime and run a sample to test the handler.

Code related to this sample can be found here[1].

Prerequisites:

OS Platform : Unix (eg: Mac or any Linux)
Java : 1.6.0 or higher.
Apache Ant(TM) : 1.8.2 or higher
Apache Airavata : 0.12 or higher (downloaded [5] or built from a stable tag/branch/trunk from Airavata Git repo[6]) .
A valid gmail account : You need to have an internet connection with correct credential for a gmail account to test this sample.
a svn client (in order to checkout the sample code)

Description: In this article we are going to write two handlers, one will get executed before we run the application and the other one will get executed after the application execution. We call the earlier handler as In Handlers (Handlers run before application execution) and later handler as Out Handlers(Handlers run after application execution). During invocation to the InHandler we are planning to read the inputs and email them to a configured email address. During the OutHandler we are planning to send an email with the Outputs of the application execution. We are going to test this Handlers with a simple echo application.

When GFAC loads a particular handler it simply use the default constructor to build the object ,then invoke the initProperties(...) method to initialize a custom initialization code. So in your handler you can write the logic to run to initialize your handler task. If you have any configuration GFAC framework supports configuring these properties in gfac-config.xml along the handler registration. So your handler configuration would looks like this with properties required to run the InputEmailHandler[2]

</Handler>

and OutputEmailHandler[3].

</Handler>

With the above features of GFAC framework we can implement the initProperties logic for these two handler to read the properties to a Java properties object like below ( properties configured in the xml snippet above will come as the argument for the initProperties and framework will invoke this operation with appropriate properties configured in the xml snippet). As the Handler author we have to use the properties and consume them in the initProperties operation. In this example we simply make the incoming properties as a private member of the handler and use it during the invoke operation.

private Properties props;

public void initProperties(Properties properties) throws GFacHandlerException {

props = properties;

}

Now to implement the real logic we have to fill the invoke operation of the GFacHandler interface. Argument for the invoke operation is JobExecutionContext, this same object will be parsed for each of the Handlers and provider for a given execution chain. During the InputEmailHandler we read the input values and create the Email message content as below.

public void invoke(JobExecutionContext jobExecutionContext) throws GFacHandlerException {

...

Map<String, Object> parameters = jobExecutionContext.getInMessageContext().getParameters();

StringBuffer buffer = new StringBuffer();

for (String input : parameters.keySet()) {

ActualParameter inParam = (ActualParameter) parameters.get(input);

String paramDataType = inParam.getType().getType().toString();

if ("String".equals(paramDataType)) {

String stringPrm = ((StringParameterType) inParam.getType())

.getValue();

buffer.append("Input Name:" + input + " Input Value: " + stringPrm + "\n");

}

message.setText(buffer.toString());

...

}

Similarly for the output reading we can implement the logic like below.

Map<String, Object> parameters = jobExecutionContext.getOutMessageContext().getParameters();

StringBuffer buffer = new StringBuffer();

for (String input : parameters.keySet()) {

ActualParameter inParam = (ActualParameter) parameters.get(input);

String paramDataType = inParam.getType().getType().toString();

if ("String".equals(paramDataType)) {

String stringPrm = ((StringParameterType) inParam.getType())

.getValue();

buffer.append("Output Name: " + input + " Output Value: " + stringPrm + "\n");

}

message.setText(buffer.toString());

Note: JobExecutionContext can be use to pass data between handlers and providers, this can keep set of properties, so one Handler can set a defined property and the other handler can read that property, because same object will be used for a given execution.

Steps to run the sample code

1. Extract the Airavata binary distribution to a directory (We will refer this directory as AIRAVATA_HOME through-out rest of this document

2. Checkout the sample code from[1] and open the build.xml file to set the airavata.home property.

ex: <property name="airavata.home" value="/target/apache-airavata-server-0.12-SNAPSHOT"/>

Note: when you open the build.xml you can see we only have a dependency to gfac-core and other airavata libraries is configured as below.

</fileset>

3. After setting the airavata.home, run the ant command to build the Handlers and this will create a jar file in dist/lib directory in the samples folder which got created in step 2.

$ ant

Ex: ls dist/lib/

airavata-gfac-handler-sample.jar

4. Now copy the jar file created in the above step and the jar files in src/main/resources (these are handler dependencies we used in our handler implementation) to AIRAVATA_HOME/lib directory.

5. Open gfac-config.xml from AIRAVATA_HOME/bin/ directory and copy the above content to localProvider configuration in gfac-config.xml. Initially local provider configuration will looks like below.

</InHandlers>

</Provider>

After copying In and Out Handlers in to the In path and Out path local provider configuration will look like below.

</Handler>

</InHandlers>

</Handler>

</OutHandlers>

</Provider>

6. Now change the username/password properties in both locations in the above configuration to your gmail credentials (Before doing that you might want to double check we simply send an email to the same account with the inputs and output values).

Note: make sure in the username section you add the full gmail like tom@gmail.com

7. Start Apache airavata server.

$ AIRAVATA_HOME/bin/airavata-server.sh

8. Run the Echo application sample

This will register an echo application with the Airavata server instance started in step 6 and launch an experiment with that application.

Note that execution of the sample requires the airavata server running in the same host.

To execute a simple “Echo” application sample, first checkout the sample Java code[4]
Update airavata.home property in the build.xml of the sample to your AIRAVATA_HOME location as in the step 2
Build and execute the sample

$ ant run

9. Now to do a double check you can simply remove the handler configuration from gfac-config.xml and restart the Apache Airavata instance and run the application again by running ant run command in local-handler-sample folder. For this execution you will not get an email.

[1]https://svn.apache.org/repos/asf/airavata/sandbox/gfac-sample/local-handler-sample

[2]https://svn.apache.org/repos/asf/airavata/sandbox/gfac-sample/local-handler-sample/src/main/java/org/apache/airavata/gfac/local/handler/InputEmailHandler.java

[3]https://svn.apache.org/repos/asf/airavata/sandbox/gfac-sample/local-handler-sample/src/main/java/org/apache/airavata/gfac/local/handler/InputEmailHandler.java

[4]https://svn.apache.org/repos/asf/airavata/sandbox/gfac-sample/local-echo-sample-client/

[5] http://airavata.apache.org/about/downloads.html

[6] http://airavata.apache.org/development/source.html

Space shortcuts

Page tree