This chapter is intended for those who want to use Soaplab to provide Web Services that will allow remote users (clients) to start analysis tools on the service provider's machine (or machines). The chapter is, indeed, intented for you if:
- You have one or more command-line analysis tools to offer.
- You wish to access them from other computers, eventually over the Internet.
- You wish to access them using your (or someone else’s) programs, not just by filling the forms and clicking on web pages.
The Soaplab can wrap - as a Web Service - (almost) any command-line tool, starting from the common UNIX tools, such as tar, sort, or ls, going to more complex sets, such the programs distributed within EMBOSS, and ending with tools that are usually executed using a independent queuing system, such as running a BLAST on an LSF.
The main task any service provider needs to do is to describe (in a way shown in details later and below) the analysis tool he/she wants to deploy. This may not be an easy job, especially if you wish to deploy many tools. Fortunately, a prominent set of tools, the EMBOSS, already has descriptions for all its tools, and Soaplab recognizes its format. Actually, Soaplab goes further and uses the EMBOSS format for descriptions for other, non-EMBOSS, tools as well.
You may find the architecture page helpful to explain the whole picture before you immerse into gory details below. Especially, the Soaplab Flow Diagram may be useful.
|
Additionally to what is distributed within Soaplab (and what is explained below in the section about available packages) you need to have and to install separately the following:
- Java
- It was tested it with JDK 1.4. There are unsolved issues with
the latest JDK 1.5 (the issues seem to be in Apache Axis itself).
- Perl
- Perl is mainly used to execute the analysis tools. It plays a
bridge role between Java and the operating system. It also means that
the whole system was always used and tested only on Unix (the clients,
however, are written in pure Java so they can be used on any platform).
However, Perl is not needed for running the Gowlab sub-project. You still need Perl for generating XML metadata files from ACD files.
- Apache Tomcat servlet engine
- Actually, it can be any servlet container (such as JBoss) - but I
have tested deployment only with Apache Tomcat.
During the Soaplab installation, you will need to know about your Tomcat server:
- A directory where your Tomcat is installed (this is because the installation will deploy there Java classes, etc.), and
- A URL accessing your Tomcat (e.g. http://localhost:8080)
- Apache Axis SOAP toolkit
- This is a set of Java libraries that do all the SOAP stuff. You
need to install these libraries into your Tomcat (or into whatever
servlet engine you are using). Follow the Apache Axis
documentation for that.
During the Soaplab installation, you will need to know about Axis:
- A directory where Axis is installed within Tomcat engine (which is by default <your-tomcat-home-dir>/webapps/axis).
- Optionally, mySQL
- The local database mySQL is used - if present - to store
results created by the analysis tools. Having results stored
means that they can be reached even after re-staring your Tomcat
engine.
During the Soaplab installation, you will need to know (if you choose to have mySQL used at all):
- A URL of your mySQL Soaplab database
- A user name to be used by Soaplab to access your mySQL Soaplab database
- A password for such user
- And, obviously, you need to have programs (tools) you want
to wrap as Web Services.
|
Soaplab for service providers is distributed in two different flavors (both are available from the download page) - a binary distribution and a CVS check-out. They both contain the same Soaplab implementation but they differ in the way how to create, deploy and add new services. You can use them together, or each one separately.
Check-out CVS
You can get the most complete Soaplab, including sources, from a CVS repository. This gives you everything on your computer, including many Ant tasks for deploying and testing Web services (Ant is a Java way how to build and use projects).
This is a good option for testing your new Web services. After you describe the analysis tools you wish to make available (this step is necessary for all alternatives) everything is done by simply invoking one or two Ant tasks. However, there is no easy way how to add new services to the existing (already deployed) ones (it still can be done by manually editing some XML files in work/metadadata but there is no support for it in the Ant tasks).
|
 |
How to build services from a CVS copy |
Use binary distribution
For a production-like and robust use, however, is more convenient the option with a binary distribution.
The core Soaplab implementation in binary distribution does not change as often as it might in CVS. It gives you more stability for your deployed services.
Note that if you have a CVS local copy you do not need to download a binary distribution, you can make a binary distribution from your latest CVS copy by using Ant task dist-binary.With the binary distribution you can also add new services by merging them with the existing ones. It requires, however, a few more steps and a few more command-line options - comparing to Ant tasks (which shield you).
|
|
How to use binary distribution |
Combine CVS and binary distributions
Actually, the best environment is to use both options. Have a CVS copy in one place where you can test your new services, and where you can create a package with those new services once they are tested. And install also a binary distribution, and add there services created in the CVS local copy.
The main advantage of this combination is that you can use an Ant task for packing together one or many services into a site-independent package (that can be shared, by the way), and by using just one script you can merge this package with existing services within your binary distribution.
Available set of services
This architecture also allows to share and re-use services packed by someone else:
|
What service packages are available |
|
Web services - when they use Axis toolkit (as Soaplab does) - can be configured by a number of deployment parameters. This section gives their overview. It is placed here because the same deployment parameters are used independently on how you deploy services (from a CVS copy or from a binary distribution).
There are here more or less for documentation purposes because by default they all are created automatically. But there may be cases...
If you are, however, reading this page the first time, you may not have enough context to understand what individual parameters means. Read on or skip it, and return here later if this is the case.You may anytime check what parameters are in use - by looking into server-config.wsdd file in <your-tomcat-home>/webapps/axis/WEB-INF directory (or similar, it depends where is Axis within your Tomcat).
Note that the default values in the tables below may differ depending on the distribution method - binary distribution may have different ones than when using the CVS module.
The general configuration parameters are shared by all services. Being in one place in server-config.wsdd it is easier to correct them manually (in case of emergency). But Soaplab services do not mind where they get deployment parameters from - they simply try first the global parameters, and then their own parameters.
| Global configuration parameters | ||
|---|---|---|
| Name | Default value | Description |
| soaplab.logfile | .../logs/soplab.log | Log file |
| jdbc.url | jdbc:mySQL://localhost/soaplab | JDBC URL to your database with results |
| jdbc.user | soaplab | Database user name |
| jdbc.passwd | (none) | Password to access database |
| jdbc.maxconn | 15 | Maximum open connection to database |
| jdbc.driver | org.gjt.mm.mysql.Driver | Class name representing a JDBC driver |
The List service is named AppLabFactory, and it uses following configuration parameters:
| Configuration parameters for a list service | ||
|---|---|---|
| Name | Default value | Description |
| className | org.embl.ebi.SoaplabServer.applab. AnalysisFactoryWSApplabImpl |
Class representing this service |
| applab_factory | .../work/IOR/AppLabFactory.ref | A location of a file with an IOR of the AppLab's Factory object (or the IOR directly). |
All other AppLab-based services (both normal and derived ones) use the following configuration parameters:
| Configuration parameters for each service | ||
|---|---|---|
| Name | Default value | Description |
| className | org.embl.ebi.SoaplabServer.applab. AnalysisWSApplabImpl |
Class representing this service |
| applab_factory | .../work/IOR/AppLabFactory.ref | A location of a file with an IOR of the AppLab's Factory object (or the IOR directly). The factory should know about this service. |
| applab_analysis | .../work/IOR/analyses/<service-name>.ior | A location of a file with an IOR of this service (or the IOR directly). This parameter - if exists - takes precedence over parameter applab_factory |
There are few more parameters used by Gowlab-based services. Their table is in the Gowlab guide.
|
|
|
How to write an ACD file |
|
I want to use Soaplab from a CVS copy |
|
I want to use binary distribution |
|
What service packages are available |
|
Last modified: Thu Mar 3 11:36:07 2005