Table of Contents
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.
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.
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
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.
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
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
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
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.
Once your source and any supporting files are present as described
above you can either call ant directly (just type
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
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.
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 thetab and either selecting individual methods or using the and 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.
To aid use of your exported API you can select thetab and use it to provide a name and description for the entire API subset:
To save the API definition select in the menu-> . 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.
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 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
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
HelloWorld to the
input of the method
As a convenience, methods also return the very same object in the
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
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
Before you can run the workflow you also need to install the
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
. The default classloader sharing is
, 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
jar files to run it, but they only need the
API consumer definition file if they are to build similar
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 sharing for all your processors and modify the Taverna startup scripts.
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.