Chapter 2. Developers Guide.

Table of Contents

1. Getting started.
1.1. Subscribing to the mailing lists.
1.2. Getting the Taverna sourcecode.
1.3. Building Taverna with Maven.
1.4. Debugging Taverna
2. Extending Taverna using a Service Provider Interface (SPI).
2.1. Available SPI's.
2.2. Declaring your SPI.
3. Creating Plugins.
3.1. Writing the Plugin.
3.2. Publishing the Plugin.
3.2.1. Deploying the Plugin artifact.
3.2.2. Describing the Plugin.
3.2.3. Installing the Plugin.
3.3. Publishing Plugin updates.
4. Using the Taverna API to programmatically execute a workflow
4.1. Initialising the Repository
4.2. Registering the repository with the Taverna SPI registry
4.3. Example application
4.4. Example source code
5. Appendix.
5.1. Useful properties.
5.2. Taverna versioning guidelines.

1. Getting started.

1.1. Subscribing to the mailing lists.

You are strongly encouraged to subscribe to the taverna-hackers mailing list. Here you will get help to many of your problems from fellow hackers or the directly from the Taverna team. It also helps the Taverna developers become aware of particular issues that they may otherwise be ignorant of.

Whilst you are at it, you would be encouraged to also subsribe to the taverna-users list.

Details of how to join the mailing lists, and browse the archives, can be found at the Taverna Sourceforge site.

1.2. Getting the Taverna sourcecode.

Even if you not planning on modifying the Taverna sourcecode directly, and are simply planning on creating a Plugin, it is still advisable that you download the sourcecode. It can provide a valuable reference on how to use various parts of the API.

When a Taverna release is made the sourcecode used to make that release is made available on the Sourceforge download site. Sourcecode bundles are prefixed taverna-workbench-src followed by the version number. If they are not available complain to the taverna-hackers mailing list.

For the very latest sourcecode you will need to retrieve the taverna1.0 module from Taverna CVS repository, using an anonymous login. Its advisable to do this within Eclipse using taverna.cvs.sourceforge.net as the Host, /cvsroot/tavena as the Repository, pserver as the Connection type, and anonymous as the username with a blank password.

The following commands will allow you to retrieve CVS from the command line, and when prompted for a password just press enter.

cvs -d:pserver:anonymous@taverna.cvs.sourceforge.net:/cvsroot/taverna login 

cvs -z3 -d:pserver:anonymous@taverna.cvs.sourceforge.net:/cvsroot/taverna co -P taverna1.0

It is also possible to Browse CVS online.

1.3. Building Taverna with Maven.

Maven, version 2.0.4, is a pre-requisite to building Taverna, as of course is Java, but inparticular Java SE 5.0.

Once the pre-requisites have been met, from the root of the Taverna directory run the command:

mvn install

This installs the artifacts into your local maven repository. Next run the command:

mvn package assembly:directory

This builds the Taverna release into the directory target/taverna-1.7.1-bin/taverna-1.7.1

Note

In theory the goal 'package' is an unnessary step, but is sadly required due to a bug in the maven assembly plugin.

Next change to the target/taverna-1.7.1-bin/taverna-1.7.1/ directory. If you are making sourcecode changes, then before you can run Taverna you need to edit the startup script, runme.sh or runme.bat depending upon your platform. If you don't make the following change then when you run Taverna it will fetch its artifacts from the central myGrid repository, rather than using the artifacts you just built and installed. You will need to know the location of your local maven repository. Using Linux or the Mac this is by default $HOME/.m2/repository, or using Windows "Documents and Settings/<user>/.m2/repository/. You need to assign this value to the variable raven.repository.0 in the startup script meaning that your local repository is examined first for the Taverna artifacts. The path needs to represented as a file URL.

So for Linux your run.sh will end with something like.

ARGS="-Xmx300m"
ARGS="$ARGS -Djava.system.class.loader=net.sf.taverna.tools.BootstrapClassLoader"
ARGS="$ARGS -Djava.protocol.handler.pkgs=uk.ac.rdg.resc.jstyx.client"

#uncomment and complete the next line and complete to change the directory taverna downloads jars to
#ARGS="$ARGS -Dtaverna.repository=<directory>"

#uncomment and complete the next line to set http proxy settings, and the 2nd line if authentication is required
#ARGS="$ARGS -Dhttp.proxyHost=<hostname or ip address> -Dhttp.proxyPort=<port>"
#ARGS="$ARGS -Dhttp.proxyUser=<username> -Dhttp.proxyPassword=<password>"

ARGS="$ARGS -Draven.repository.0=file:/home/elvis/.m2/repository/"

java $ARGS -jar $TAVERNA_HOME/taverna-bootstrap-1.7.1.jar $@

In Windows, note the spaces in the path need to be replaced with %20:

set ARGS=-Xmx300m
set ARGS=%ARGS% -Djava.system.class.loader=net.sf.taverna.tools.BootstrapClassLoader
set ARGS=%ARGS% -Djava.protocol.handler.pkgs=uk.ac.rdg.resc.jstyx.client
set ARGS=%ARGS% "-Dtaverna.dotlocation=%~dp0\bin\win32i386\dot.exe"

REM uncomment the next line and complete to change the directory taverna downloads jars to
REM set ARGS=%ARGS% -Dtaverna.repository=<directory>

REM uncomment and complete the next line to set http proxy settings, and the 2nd line if authentication is required
REM set ARGS=%ARGS% -Dhttp.proxyHost=<hostname or ip address> -Dhttp.proxyPort=<port>
REM set ARGS=%ARGS% "-Dhttp.proxyUser=<username> -Dhttp.proxyPassword=<password>"

set ARGS=%ARGS% "-Draven.repository.0=file:/C:/Documents%20and%20Settings/Elvis/.m2/repository/"

java %ARGS% -jar "%~dp0\taverna-bootstrap-1.7.1.jar" %*

Tip

During constant development it can become a pain, to put it politely, to need to run mvn package assembly:directory and edit the runme script each time. Fortunately there is a way around this. Copy the edited runme script to the root folder of the Taverna project, and edit it once more so that the final java command invokes the taverna-bootsrap-1.7.1.jar in taverna-bootstrap/target/, e.g. in Linux:

java $ARGS -jar taverna-bootstrap/target/taverna-bootstrap-1.7.1.jar $@

or Windows:

java %ARGS% -jar "target\taverna-bootstrap\taverna-bootstrap-1.7.1.jar" %*

You will then only need to run 'mvn install' each time and then start Taverna using your new script.

1.4. Debugging Taverna

A useful technique when debugging Taverna is to use the Remote Debugging facilitiy java offers. This has the advantage that you will be debugging Taverna under conditions that it normally runs, together with its modified classloaders. Debugging in this way is actually very straightforward. First you need to add the following VM arguments to your startup script.

-Xdebug -Xrunjdwp:transport=dt_socket,suspend=n,server=y,address=8000

In Eclipse you can then configure a "Remote Java Application" from the Debug Dialog, using the port defined by the address setting within the connection properties (8000 in the example) . You will also need add the Taverna project from the Source tab.

Once you have started Taverna using your modified startup script, you can then start you newly configured Remote Java Application which will then connect to the listening port and stop at your breakpoints just as you would normally debug an application within Eclipse.

Likewise you can debug in Netbeans in a similar way by selecting the menu option Run->Attach Debugger.