An Introduction to Web Services

1
An Introduction to Web Services

• Dr. Katy Wolstencroft
• myGrid
• University of Manchester

2
Exercise 1 Beanshell Scripting
3
Beanshell Scripting

• The beanshell scripting host allows you to add
  simple java scripts to your workflows.
• The beanshell code is contained within the
  workflow xml file (the scufl file).

4
Beanshell

• Open Taverna and load the workflow
• compareXandYfunctions.xml
• Look at the diagram. Each brown service is a
  beanshell script
• In the Advanced Model Explorer (AME)select the
  beanshell GetUniqueIDs
• Right-click and select configure beanshell

5
Beanshell

• Look at the script and see if you can work out
  its function
• Look at the ports and their types as well as the
  script

6
Beanshell Background

• BeanShell is a natural scripting language for
  Java
• Beanshell executes java statements and
  expressions, but not ALL java
• In the next section you will be asked to write
  your own beanshell script. To get a better idea
  about what you can and cant use in beanshell,
  please use the beanshell manual as a reference
• http//www.beanshell.org/manual/contents.html

7
Creating a Beanshell Script

• Load the workflow at
• http//www.cs.man.ac.uk/katy/taverna/beanshellExa
  mple.xml
• This workflow collects gene ontology data from
  ensembl relating to a particular disease
• Run the workflow
• Each piece of data is in a separate output file.
  This is hard for the user to interpret
• The other problem is that it generates lists. How
  do you know which outputs from which lists belong
  together?

8
Creating a Beanshell Script

• In the available services panel, select a
  beanshell scripting host from the Local services
  section and add it to the workflow
• Right-click on the beanshell scripting host in
  the AME and select configure beanshell
• Write a simple beanshell script that collects
  each output into a simple report showing
• Ensembl_ID, GO_ID, GO_description and GO_evidence
  code
• Before you write the script, you will have to
  define the names of the input and output ports by
  typing them into the textboxes on the port pane

9
Creating a Beanshell Script

• Once the script is written, it cannot be tested
  until the workflow is run
• Connect the outputs of the biomart service to the
  inputs of the beanshell service
• Create a new output for the beanshell report and
  connect it up
• Finally, look at the iteration strategy for the
  beanshell script is it appropriate? Does it
  need to be cross product or dot product?
• Run the workflow to test your script and your
  iteration strategy

10
Building Beanshell

• For more beanshell scripting practice, close the
  current workflow and select a new beanshell
  processor
• Write a simple script that takes an input of a
  number and adds 1000 to it
• Hint you will need to define not just the
  script, but the input and output ports
• Add an input and output to finish the workflow
  and run the workflow

11
Beanshell Notes

• Beanshells are most often used as shim
  services.
• A shim is a service that doesnt do anything
  scientific, but helps two scientific services fit
  together. For example, by changing the format of
  incompatible files or by mapping between database
  resources

12
Beanshell Notes

• Beanshells are useful within workflows, but
  cannot be shared out of the context of the
  workflow file. If you want to provide a service
  to be easily shared by the community, it is
  better to host a web service

13
Exercise 2Installing Required software
14
Installing Tomcat

• Download tomcat (version 5.0.28) from
  http//tomcat.apache.org/
• Unzip and untar
• Cd into the conf directory and find the
  server.xml file
• Edit the server.xml file to use a port of your
  choice
• The default is 8080 (so search for 8080 in the
  file) if we are all using the same machine, we
  will need to change this!

15
Installing Tomcat

• Cd into the bin directory
• Set the JAVA_HOME environment variable to point
  to jsdk
• Export JAVA_HOME/yourJava
• Start the tomcat server using
• ./catalina.sh start
• Find the tomcat webpage at
• http//localhostportnumber

16
Installing Apache Axis

• Download the latest version of apache axis from
• http//ws.apache.org/axis/
• Unzip and untar the installation
• Move the axis directory from webapps to the
  tomcat webapps directory
• Restart tomcat using ./catalina.sh stop then
  ./catalina.sh start in the tomcat bin directory

17
Axis

• Find out if axis is installed correctly by
  looking at
• http//localhostportnumber/axis
• Look at the happy axis page
• Find and install any missing .jar files

18
Exercise 3Axis Instant Deployment
19
Apache-axis Web Services

• Can use instant deployment
• Or custom deployment
• Today simple examples of each
• Can use native java code, or a JDE of choice

20
JWS Instant Deployment

• Java Web Services Files
• This is the easiest way to deploy a web service
  its just like writing ordinary java code!
• Write some code to split a list of fasta sequence
  files into single files

21
Example

• public class FastaLister
• public String lister(String file)
• return file.split("\n(?gt)")
• or use your own example

22
Deployment

• Compile your java code
• Copy into your axis installation
• (this will be /path-to-tomcat/webapps/axis)
• Copy the java file FastaLister.java to
  FastaLister.jws
• Restart tomcat
• and you are done!

23
Finding your service

• The new service can be found at
• http//localhostportnumber/axis/FastaLister.jws
• Follow the link to the WSDL
• Copy the WSDL address
• Add to the Taverna services panel by selecting
• Add new WSDL scavenger

24
Build workflow

• Use your new web service in a workflow to
  separate the list of fasta files here
• http//www.cs.man.ac.uk/katy/taverna/fastaFile.tx
  t
• And blast each sequence against the swissprot
  database
• Save your workflow

25
Exercise Extension (optional)

• Build your own Hello World example
• Write a java script that writes the traditional
  greeting and deploy it using jws

26
Advice from Axis

• Important JWS web services are intended for
  simple web services. You cannot use packages in
  the pages, and as the code is compiled at run
  time you can not find out about errors until
  after deployment. Production quality web services
  should use Java classes with custom deployment.

27
Exercise 4Custom Deployment
28
Custom Deployment

• For custom deployment, the code is again like
  writing ordinary java, but this time you need to
  create a Web Service Deployment Descriptor
  (WSDD) file
• Axis uses the WSDD to direct SOAP calls

29
WSDD File Example

• ltdeployment xmlns"http//xml.apache.org/axis/wsdd
  /"
• xmlnsjava"http//xml.apache.org/axis/wsdd/provi
  ders/java"gt
• ltservice name"MyService" provider"javaRPC"gt
• ltparameter name"className" value"FastaLister"/gt
• ltparameter name"allowedMethods" value""/gt
• lt/servicegt
• lt/deploymentgt
• The interesting part is the service section.
• The service name is the name of the service to
  the client

30
Writing a service with a WSDD

• For this exercise we will use the same
  FastaLister example
• First we need to build a deploy.wsdd file for
  this class

31
Writing a service with a WSDD

• Copy the deploy.wsdd file from the previous page
  to the /axis/WEB-INF/ directory
• Copy the FastaLiser.jws file to the directory
• /axis/WEB-INF/classes
• copy FastaLister.jws to FastaLister.java and
  compile the code
• Now we need to add the Jars in the
  axis/WEB-INF/lib directory to the classpath
• Move to the axis/WEB-INF/lib directory

32
Setting the Classpath

• Add the following jars to the classpath (NOTE
  the exact versions of these may be different for
  you)
• Axis.jar
• Commons-discovery-0.2.jar
• Commons-logging-1.0.4.jar
• Jaxrpc.jar
• Saaj.jar
• Log4j-1.2.8.jar
• Wsdl4j-1.5.1.jar

33
Deploying the service

• We need to send this file to an Axis server to
  deploy the described service
• We can use the admin client to do this by typing
  the following
• java org.apache.axis.client.AdminClient -l
  http//localhostportnumber/axis/services/MyServic
  e deploy.wsdd

34
Writing a service with a WSDD

• The service is now accessible by SOAP
• To test it go to
• http//localhostportnumber/axis/services
• You should see your service in the list
• Click on the wsdl link and copy the wsdl location
• Add your new service to the service panel in
  taverna
• Reload the previous workflow and replace the
  FastaLister in the original workflow with this
  service
• Run the workflow and look at the results

35
Exercise 5 SoapLab
36
SoapLab Notes

• The following pages describe a hands on soaplab
  exercise, but soaplab can only be installed on
  linux/unix.
• You may not have access to a linux/unix server,
  so these exercises will be demonstrated from the
  front
• Soaplab allows you to wrap legacy code as web
  services and is based on perl rather than java

37
Installing Soaplab

• Go to the soaplab web page
• http//www.ebi.ac.uk/soaplab/
• Follow the links to the download site at
  sourceforge by selecting downloads -gt
  distribution site -gt sourceforge
• Download file analysis-interfaces-2005-04-25.tar.g
  z from the download soaplab page

38
Soaplab

• Unzip and untar analysis-interfaces-2005-04-25.tar
  .gz
• cd into analysis-interfaces
• Read INSTALL.pl
• Run INSTALL.pl and answer the questions in the
  wizard
• Run ws/delopy-web-services and follow on-screen
  instructions

39
Soaplab

• Soaplab should now be installed and working
• To test it, we must see if we can run the test
  services in Taverna

40
Soaplab

• Find the address of the wsdl files
• http//localhostportnumber/axis/services
• View the list of services

41
Add Soaplab Services to Taverna

• Open the Taverna workbench and right-click on
  available processors at the top of the services
  panel
• Select Add new soaplab scavenger
• Copy in the address for the new services
• Look at the new services at the bottom of the
  panel. Try to invoke them

42
Soaplab in Taverna

• You should now have a working soaplab
  installation that you can use with Taverna
• Now we will look at creating additional services
  to add to the collection
• Soaplab wraps legacy command-line applications

43
ACD Files

• The ACD files describe parameters of command-line
  programs that you want to make into web services
• You must define
• The path to the executable
• The format of the command-line
• Each command-line parameter, their formats and
  whether they are mandatory or optional

44
An example

• appl HelloWorld
• documentation "Classic greeting from the
  beginning of the UNIX epoch"
• groups Classic"
• nonemboss "Y"
• executable "echo"
• string greeting
• additional "Y"
• parameter "Y"
• default "Hello World"
• comment "defaults"
• outfile output
• additional "Y"
• default "stdout"

45
ACD Application Attributes

• documentation
• A string describing briefly the function of the
  program.
• groups
• This attribute allows to group programs together
  based on their functionality. Its value contains
  the name(s) of the group(s). When an application
  belongs to more then one group, the group names
  must be separated by either a comma or
  semi-colon.
• supplier
• It identifies in a free-text who is supplying
  this application.
• version
• A version of this application, a free-text.
• executable
• A name of the executable representing this
  application. If missing the application name
  (defined in the appl line) is used instead. It is
  not recommended to put here the full path - that
  would make the ACD file non-portable. The path
  can be added later and elsewhere. An example was
  given above for the hellowold application where
  the executable was the Unix program echo.
• nonemboss !
• A boolean parameter that should be always used
  and should have always value Y. By default, all
  ACD files are assumed to describe EMBOSS
  applications. But Soaplab (precisely the
  generator of the metadata XML files) does
  slightly different things for EMBOSS and
  non-EMBOSS programs - so it needs to know what
  kind of application is being described. This is
  quite important attribute.

46
Example ACD File Elements

• standard
• A boolean parameter. Value Y indicates that this
  is a mandatory parameter.
• additional
• A boolean parameter. Value Y indicates that this
  is an optional parameter.
• parameter
• Defines that this parameter appears on the
  command line without its name as a qualifier.
  Also implies that the value is required. Any
  parameter without this attribute will appear
  (unless an attribute template is specified) on
  the command line as a tagged value
• -ltparameter-namegt ltparameter-valuegt With this
  attribute it will appear as a simple value
  without any qualifier.
• default
• Defines the default value for the parameter.
• prompt
• Defines briefly what this parameter means.
• information
• More detail information about this parameter.
• help
• Very detail information, preferably containing a
  URL pointing to a complex description.
• knowntype
• A term, usually an ontology term, defining
  semantic of the data described by this parameter.
  It may be used by component-based software to
  find how can individual programs be bound
  together (what data flows between them are
  valid).
• template
• Sometimes not all parameters are expressed on the
  command-line as a simple value or a tagged value
  with the tag prefixed by a minus. For them, use a
  template string defining how the parameter should
  appear

47
Hello World Again
Application Name
Description of Function

• appl HelloWorld
• documentation "Classic greeting from the
  beginning of the UNIX epoch"
• groups Classic"
• nonemboss "Y"
• executable "echo"
• string greeting
• additional "Y"
• parameter "Y"
• default "Hello World"
• comment "defaults"
• outfile output
• additional "Y"
• default "stdout"

Path or pointer to the executable
Type of Parameter and its name
An optional parameter boolean Y yes
Appears on the command line without its name as a
qualifier
The default value for the parameter
Service writes to standard out
48
Exercise 6Deploying a New Service
49
Deploying a brand new service

• Download the file concat_two_files.pl from
• http//www.cs.man.ac.uk/katy/taverna
• Copy it into the run directory in soaplab
• This script takes two files and concatenates them
  according to the users instructions
• Try and build an acd file for this script in the
  metadata directory
• Hint start with writing down the method (the
  command line arguments) These will determine how
  many blocks of code you will need

50
Writing an ACD file

• The script contains
• my input_file_1 ""
• my input_file_2 ""
• my iteration "dot"
• my separator "\t"
• So the command line would be
• "method file_1 file_2 iteration
  separator output"

51
Writing an ACD file

• Write the ACD code block for each of the method
  items
• When the acd file is complete, mv to the
  generator directory in soaplab
• Run ./acd2xml d l Applications.xml
  concat_two_files helloworld
• This will automatically generate an xml file that
  is deployed into a WSDL and will copy the
  definition into the Applications.xml file in the
  metadata directory
• Note The helloworld is listed here also
  effectively redeploying both services

52
Deploying

• For the new service to be active, you will need
  to restart the applab server that soaplab runs on
  top of
• Find the current running applab server by typing
• Ps U username o args o PID
• Kill -9 the id of the job running
• /bin/sh ./run-AppLab-server
• Restart applab by running nohup
  ./run-Applab-server from the soaplab directory

53
Deploying

• Run the command ws/deploy-web-services d
• This will create the WSDL file and deploy the
  service within soaplab
• Look at the axis web page to see if the service
  deployed correctly
• To see the new service in Taverna. Remove the
  current service from the list and re-import from
• http//localhost/portnumber/axis/services