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 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.
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.
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.
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
tab 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 the
tab 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 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
. 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
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 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.