How to develop a BioMoby service

The main thing to understand is that MoSeS does not give you a full implementation of your service. You still need to program the business logic (e.g. to extract data from your database) - but you do not need to worry about the BioMoby and SOAP protocol details.

A typical situation is to develop (to implement) your service in a separate directory, not within your local copy of jMoby. This document describes exactly that.

The major jMoby components used for a new service development are:

• MoSeS - Moby Services Support, and
• BioMoby Dashboard.

Table of Contents

Step 1: What is needed

Second, you will need jMoby itself. Take it using a CVS checkout. Details are in a separate document, here only a quick guide:

• Check-out jMoby (password is cvs):

  cvs -d :pserver:cvs@cvs.open-bio.org:/home/repository/moby login
  cvs -d :pserver:cvs@cvs.open-bio.org:/home/repository/moby co -P moby-live/Java
  cd moby-live/Java
  

• Build jMoby (and create a jar file with jMoby libraries)

  ant jars
  

• Start BioMoby Dashboard in order to fill local cache with BioMoby entities (this may take a while when it runs the first time):

  ant dashboard
  

Then, you need a space (a directory) where you are going to develop your service. One possible way is to use an empty project in empty_project.tar.gz. You can develop anywhere, and you can use any tools, of course. This document just needs to explain connections between the jMoby (now checked-out in moby-live/Java directory) and your project. It will be, therefore, using the suggested empty project as an example. Note, that especially you can develop using Eclipse - and still using the suggested empty project.

I will be using a name MyPoject for the new project directory. Go where you wish to have your new project and:

cp ....moby-live/Java/docs/empty_project.tar.gz .
tar xzf empty_project.tar.gz
mv EmptyProject-RENAME-ME MyProject
cd MyProject
cp ....moby-live/Java/build/lib/jmoby.jar lib/

cp ....moby-live/Java/lib/alltools.jar lib/
cp ....moby-live/Java/lib/jdom.jar lib/
cp ....moby-live/Java/lib/xercesImpl.jar lib/
cp ....moby-live/Java/lib/xml-apis.jar lib/

In order to build everything you need an Apache Ant installed, a Java-based build tool. If you are using Eclipse, it is already part of it.

This is how you will be building everything (now it does little because you do not have any source code there yet):

ant all

ant

Step 2: Service registration

cd moby-live/Java
ant dashboard
Setting -> Panel selection -> Registration -> Service Registration

Step 3: Service generation

cd moby-live/Java
ant dashboard
Setting -> Panel selection -> MoSeS Generator

Select service...: your-service-name
Button: All-in-One: Do it all

This also packs generated code into two jar files that you need to copy to your project directory:

cd MyProject
cp ...moby-live/Java/build/lib/biomoby-datatypes.jar lib/
cp ...moby-live/Java/build/lib/biomoby-skeletons.jar lib/

Step 4: Service implementation

Put your implementation sources into MyProject/src/main - using any package structure as you wish. An example of an implementation is in MoSeS.

The skeleton API documentation (you need to know it in order to find what methods are available in your implementing class) is available in moby-live/Java/docs/APIservice/index.html.

You compile by calling:

ant

ant -projecthelp

Step 5: Service testing

There are many BioMoby clients that can be used to call our services. Let's show two of them. One is a command-line program that is the best for fast debugging, the other one is again the BioMoby Dashboard.

Command-line testing

build/run/run-service -help

Check also the log file project.log.

Testing with Dashboard

cd moby-live/Java
ant dashboard
Setting -> Panel selection -> Simple Client
Select service...: your-service-name
add your input data on the right
Button: Call service

Here also, you can test your service before it is deployed. Check the box Use this local class and enter a full name of your service implementation class. This, however, will not work - because Dashboard is started from the jMoby directory and it does not know anything about your implementation classes. Your classes are not on the Dashboard's CLASSPATH. The best way to rectify this is to copy script moby-live/Java/build/run/run-service to your project directory, edit it (see what build/run/run-* scripts how to set your CLASSPATH), and start Dashboard by calling the new script.

Step 6: Service deployment

Before any deployment, make sure that:

• A Tomcat (or other servlet engine) is installed.
• An Apache Axis is installed in your Tomcat.

The Dashboard knows what jMoby files are needed and what are the service and implementation class names. But Dashboard does not know anything about files coming from your project. For that, there is an Ant task that collects all needed files and put them in MyProject/build/lib:

cd MyProject
ant pre-deploy

The core of deployment is done by the BioMoby Dashboard in the MoSeS Generator Panel:

cd moby-live/Java
ant dashboard
Setting -> Panel selection -> MoSeS Generator

Pattern for implementation class names: your-package-name.{SERVICE}Impl
Select service...: your-service-name
Button: Deploy

Before you press the Deploy button check at least these three things:

• Check where you are going to deploy: on a local or on a remote machine. The panel's help explains differences.

• Type the name of the directory with your jar files (created by the Ant's task pre-deploy above) into the field Directory with user's jar files. This is how Dashboard learns about your implementation files.

• Make sure that the implementation class name (in the table column Implemented by class) is correct.

After deployment, restart your Tomcat (I recommend to use Tomcat Manager and to reload only Axis), and try the service, now using its real endpoint.