Step By Step Guide to the first service

This is almost a list of bookmarks of the more detailed guides, with some text around. The details are good, but here you will get, hopefully, just an essence, a quick get started flavor.

It is written around a short tutorial for the Soaplab2 service providers given at the Taverna/Soaplab2 workshop in October 2007 at EBI.

Pre-prepared services
Your own services

Pre-prepared services

First, make sure that the distributed, testing Soaplab2 services can run on your machine:

Make sure that your machine has the required software:

Java 1.5.or later
Ant 1.6.5 or later
Apache Tomcat 5.x or later

Download Soaplab2. Now you should have a directory soaplab2. Go there.
Create a file build.properties by copying it from build.properties.template. Add there the property tomcat.home pointing to a directory where you have installed your Tomcat, and the property tomcat.host with the host name of your Tomcat. For example:
```
tomcat.home = /home/senger/Software/jakarta-catalina
tomcat.host = www.my.server
```
Install and build Soaplab2:
```
ant install
```

Now you have installed the testing services that were included in the Soaplab2 distribution. Run them locally - because you have not yet started your Tomcat server - using the Soaplab2 main command-line client:

build/run/run-cmdline-client -protocol local -name testing.files -i
build/run/run-cmdline-client -protocol local -name testing.files -w -r
build/run/run-cmdline-client -protocol local -name testing.files -w -r input_direct_data abc
build/run/run-cmdline-client -protocol local -name testing.files -w -r \
                              input_url \
                              https://sites.google.com/site/martinsenger/testing.page.xml.txt

But with the following input:

build/run/run-cmdline-client -protocol local -name testing.files -w -r input_url /etc/hosts

there is a security problem (which should be, because you do not want all your local files to be exposed to the Soaplab2 clients from all over the world):

===ERROR===
Soaplab::NotValidInputs
[input] Refusing to resolve the reference: /etc/hosts
===========

Let's start playing using real Web Services protocol (by the way, have you called ant jaxdeploy at the end of step 4, as suggested in the prompt there?): Start your Tomcat server and open the page http://localhost:8080/soaplab2/ - and you should be able to see them and to use them (using the Spinet Web client).

Your own services

Now, it is time to create your own service. We are going to create a Gowlab service, returning a geographical coordinates (and other details) of the given geographical place, using a wonderful public database geonames.org.

Create an ACD file (metadata description) for the new service - use the file path and name src/etc/acd/gowlab/search.acd:

appl: Search [
  documentation: "Returns the geographical coordinates of the given place names"
  groups: "geonames"
  nonemboss: "Y"
  supplier: "http://ws.geonames.org/search"
  comment: defaults
  comment: "help http://www.geonames.org/export/geonames-search.html"
]

string: place  [
  qualifier: q
  default: "Prague capital of Czech Republic"
  help: "Search this place in all possible attributes:
         place name, country name, continent, admin codes, etc.
         The search is using an AND operator." 
]

list: type  [
  min: 1
  max: 1
  values: "xml;json;rdf"
  default: xml
  prompt: "The format of the returned document"
]

list: style  [
  min: 1
  max: 1
  values: "SHORT;MEDIUM;LONG;FULL"
  default: MEDIUM
  prompt: "Verbosity of returned XML document"
]

outfile: result  [
]

Go through the ACD file above and check with the metadata guide what the individual data types and attributes mean.

Create Soaplab2 run-time XML metadata from the ACD format:
```
ant gengowlab
```

Try it locally:

build/run/run-cmdline-client -protocol local -name geonames.search -i
build/run/run-cmdline-client -protocol local -name geonames.search -w -r
build/run/run-cmdline-client -protocol local -name geonames.search -w -r type json place "Saffron Walden"
build/run/run-cmdline-client -protocol local -name geonames.search -w -r type json place "Saffron Walden" style FULL
build/run/run-cmdline-client -protocol local -name geonames.search -w -r type rdf style FULL

Deploy all services, including the new one, to your Tomcat server:
```
ant jaxdeploy
```
You can also deploy the same services using an old-fashioned protocol that is understood and used by the old Soaplab1 clients:
```
ant axis1deploy
```
Finally, try your new service using the Spinet Web client. Going to (unless your Tomcat is running on a different port) http://localhost:8080/soaplab2/ and clicking on geonames.search service:

you should see the new service panel:

Clicking on the Run service button results in the result page like this:

Or, with the FULL style, this one.

Last modified: Sat Sep 4 09:46:41 2010