6. Additional optional tools

Table of Contents

6.1. API Consumer
6.1.1. Prerequisites
6.1.2. Setup
6.1.3. Usage
6.1.4. Adding methods to API definition
6.1.5. API level metadata.
6.1.6. Saving the API definition file.
6.1.7. Using the API consumer processor from Taverna
6.1.8. A word of advice
6.2. Webservice Data Proxy
6.2.1. Description
6.2.2. Initial Configuration and Installation
6.2.3. Adding Webservices
6.2.4. Configuring Webservices
6.2.5. Referencing in action.
6.2.6. Data dereferencing
6.2.7. Data housekeeping
6.2.8. Current constraints and future work.
6.3. Interaction Service Server
6.3.1. Setup
6.4. Remote Execution Server
6.4.1. Configuring the database
6.4.2. Installation
6.4.3. Administration
6.4.4. Security Considerations

These are additional tools that have been developed alongside Taverna. These require additional downloads available from the Taverna sourceforge download area in the 'taverna utilities' section.

6.1. API Consumer

The API Consumer allows the selection of subsets of Java APIs which may then be imported into Taverna's workbench software and used as components within workflows in that environment. This tool is intended for API developers rather than end users, it produces an XML API definition file which Taverna imports - it is this file that you can distribute alongside or within your API to 'Taverna enable' it. If you simply want to use parts of an existing API, it is probably easier to do this using beanshells with dependencies. As always, also consider exposing the API as a proper web service that will be accessible for Taverna users without requring any installation.

To prepare an API for consumption by the API consumer, you will need to download the API Consumer tool. Users of the prepared API will only need to download your JAR files and the generated description XML, but to produce that description you will need to use the tool.

6.1.1. Prerequisites

The API Consumer is a Java Doclet and uses Ant to launch, you must therefore have a Java JDK and ant installed and available on the path. In addition the tools.jar file from the JDK must be available on the classpath, you can copy it into the jre/lib/ext directory within your JDK installation with no unpleasant side effects.

6.1.2. Setup

We assume you have downloaded and unpacked the API consumer tool.

Before running the API Consumer you need to place the source files of the API in question within the target directory and any supporting libraries required in the lib directory. The reason the tool requires the source code is mainly to be able to resolve doclet annotations and parameter names of methods.

Adding supporting libraries is particularly important - if your API includes methods which consume or return a type that isn't available to the API Consumer the definitions it generates will be invalid. For example, if your API contains a method void foo(MagicClass bar) and the MagicClass is in some random package in a third party jar file that you haven't included there's no way for the doclet to know the fully qualified classname of MagicClass. As Taverna's plugin requires full classnames this will result in an API that can't be invoked from the workflow. You can normally trap these issues by watching for the standard javadoc warning messages in the console.

6.1.3. Usage

Once your source and any supporting files are present as described above you can either call ant directly (just type ant on the command line while in the API consumer directory) or, on Windows machines, by running the runme.bat file. The API consumer itself will be built from source and applied to the target source files, after some slight delay for this process (longer for very complex APIs) you should see a screen such as the following:

The tree on the left hand side of the window shows the available classes (including inner classes where present) along with a search box - the right hand side currently shows nothing. Selecting a class from the tree produces a display like the following, this should be clearly similar to the information produced by the standard javadoc tool:

In the case of large APIs the search box can be used to display a subset of the complete class tree - enter a pattern to match and hit return in this text box and the tree will be expanded to show all matching nodes. To return to the view with all nodes expanded clear the text in this box and hit return.

6.1.4. Adding methods to API definition

The next step is to select methods to add to the API definition - these methods (static, instance or constructors) will appear as components within Taverna's workbench when the definition file is imported.

Using Graphical Interface

Methods can be manually added by choosing the class, opening the Methods tab and either selecting individual methods or using the Select all and Clear all buttons:

Using JavaDoc tags

For APIs under your direct control there is an alternative based on JavaDoc tags. By adding the tag '@taverna.consume' to either classes or individual methods you can automatically have these methods selected in the API consumer when it first scans the source files. In the case of the tag at a class or interface level all constructors and methods will be selected.

6.1.5. API level metadata.

To aid use of your exported API you can select the API Description tab and use it to provide a name and description for the entire API subset:

6.1.6. Saving the API definition file.

To save the API definition select in the menu File -> Save as XML. This should bring up a standard save dialogue, choose a filename and save. This is the definition file that is then to be imported into Taverna's scavenger panel.

6.1.7. Using the API consumer processor from Taverna

In theory, everything you need to distribute to your workflow designers will be the API compiled and packaged as a jar file, in addition to any dependency jar files. To import the API consumer definition file into Taverna, right click on Available Processors in the Scavenger panel. Select Add new API Consumer... and select the previously saved definition file, say my_api.xml. A new branch should be added to the scavenger panel, showing the class names and methods you previously ticked off in the API consumer tool.

In this lightweight example, our exposed API only has a constructor and a single method. Using the API consumer you have to build up the calls to the API as part of your workflow, so as sayHello() is a method on the HelloWorld instance, we first have to call the constructor, and then call the method on the returned object. We'll add both API consumer processors to the workflow. Each parameter of the method is exposed as an input port, and the return value is shown as an output port. In our example, our methods don't take any parameters except the implicit object reference this, which we'll have to provide by connecting the object output of the constructor HelloWorld to the object input of the method sayHello.

As a convenience, methods also return the very same object in the output port object, so that methods that needs to be run in a particular sequence can be chained to pass their object reference, in effect preventing execution of the second method before the first method is returning it's result and object reference. Note that the Java objects can only be passed to other API consumer processors (and only if they are serializable), if you want any useful inputs and outputs to interact with your workflow you need to use basic types such as String, in our example sayHello() returns a String that is connected to the workflow output msg. Static methods don't need the object reference, and hence don't need the constructor call, unless you need to pass an instantiated object as a normal argument.

Before you can run the workflow you also need to install the required jar files and specify the dependencies in the workflow. This functionality is very similar to how to use dependencies for beanshell, so this section won't go in detail. We refer to the beanshell section Depending on third-party libraries for more information. Right click on the processor and select Configure dependencies. The default classloader sharing is Shared for whole workflow, so you only need to tick of the dependency jar files on one of the processors, like the constructor.

Users who receive your workflow will need to install the same required jar files to run it, but they only need the API consumer definition file if they are to build similar workflows.

Note that if your API is using JNI, or one of it's dependencies uses JNI, which is a native library with binding for Java, you need to take some special considerations, as explained in the section JNI-based native libraries. In particular, you need to select the System classloader sharing for all your processors and modify the Taverna startup scripts.

6.1.8. A word of advice

Depending on the complexity of your API, building workflows in this way can turn out to be a very cumbersome way to do graphical Java programming in a workflow. In many cases, writing a tiny beanshell script using the same dependency mechanism can give you most of the benefits in a smaller amount of time. By splitting the beanscript into several processors you can achieve the explicitly you need to explain the workflow. However, the API consumer gives you one major advantage, the workflow designer don't need to know much about Java, and she will see a browsable structure of your API in the scavenger panel, just like the bundled services. The workflow designer does need to know how to use your API though, but if you have explicitly designed it to be easy to use from Taverna that barrier can be lowered significantly.

An API that is useful for many people could also be wrapped as a WSDL web service using tools such as Axis and exposed on the Internet through a container such as Tomcat, which would make it usable for any Taverna workbench without requiring installation of your JAR files and definition files.