This tool is intended for API developers rather than end-users.
API Consumer Tool produces an XML API definition file based on the Java JAR file containing your library. Taverna can import such a file and, together with the JAR file containing the library, enable the use of selected classes and methods from the library as services inside workflows.
To prepare the API for consumption by Taverna as API Consumer services, you need to download and install the API Consumer Tool. Users of your prepared API will only need to download your JAR files and the generated description XML. The API Consumer Tool is only needed to produce the description file.
If you simply want to use parts of an existing API, it may be 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 requiring any installation.
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 Tool 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 that consume or return a type that is not available to the API Consumer service in the workflow 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 have not included, there is no way for the doclet to know the fully qualified classname of
MagicClass. As API Consumer service in Taverna requires full classnames this will result in an API that cannot 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, from the API Consumer Tool directory you can either run the
runme.sh script or call
ant directly (just type
ant on the command line). The API Consumer Tool itself will be built from source and applied to the target source files of your API. 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 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 in the search box at the top of the window and hit return - 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.
Adding methods to API definition
The next step is to select methods to include in the API definition file. These methods (static, instance or constructors) will appear as services in the Service Panel of the Taverna Workbench once 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 such 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.
API level metadata
To aid the use of your exported API in Taverna, you can select the API Description tab and use it to provide a name and description for the entire API subset.
Saving the API definition file
Once you have finished with selecting the classes and methods you wish to expose and described them, you should save the API definition to a XML description file.
This should bring up a standard save dialogue where you can choose a filename and save. This file can now be imported in the Taverna Workbench to enable the use of your API as services in workflows.
Read more on how to import and use API Consumer services from Taverna.