Guide for calling Soaplab based EMBOSS Web Services

For programmatic access to Soaplab based EMBOSS Web Services most of the standard Web Services client libraries can be used, alternatively when programming in Java it is possible to use Soaplab Client Library distributed as part of Soaplab. Programming against Soaplab typed interface is generally recommended as it includes input/output type definitions at WSDL/XSD level.

You can find below an example Perl script that use the typed interface to call two example EMBOSS Web Services. If you decide to use Soaplab client library we have an example Java program below that lists all available Web Service categories in the EBI Soaplab server and retrieves an example Uniprot entry using the seqret Web Service.

Alternative ways of accessing to Soaplab Web Services that requires no programming effort would be listed as follows

• Soaplab client script, distributed as part of Soaplab, example usage is given below
• Taverna workbench, design and execute workflows that can consume Soaplab Web Services
• Tools similar to soapUI, in this case we recommend use of the typed interface
• Spinet web interface, call EMBOSS programs through usual HTML forms

Soaplab-2 command-line client is a typical testing tool that covers the most functionality of the Soaplab features. Although its user-friendliness is limited it can be used for batch and automated Soaplab services calls. It supports both Soaplab-1 and Soaplab-2 servers. You need to install Soaplab clients module to have the Soaplab command-line client script installed in your system.

In order to see the list of options, type:

build/run/run-cmdline-client -help

To access the list service running at the EBI Soaplab server you may try to use:

 build/run/run-cmdline-client -l\
     -e http://www.ebi.ac.uk/soaplab/services -protocol axis1

You will get names of all available services. These are the names you need to know when making service calls.

Here are some examples to try:

build/run/run-cmdline-client \
  (1)       -e http://www.ebi.ac.uk/soaplab/services/edit.seqret \
  (2)       -name edit.seqret \
  (3)       sequence_direct_data aaaaaccccc  \
  (4)       osformat embl \
  (5)       -w \
  (6)       -r

where (1) shows where to go, (2) says what service to invoke, (3) and (4) are named input data, (5) means “create a job, start it and wait for its completion”, and finally (6) says “give me all results”.

build/run/run-cmdline-client \
  (1)       -e http://www.ebi.ac.uk/soaplab/services/edit.seqret \
  (2)       -name edit.seqret \
  (3)       -i \
  (4)       -o \
  (5)       -t \

where (3) shows all input data names, (4) shows all result names, and (5) gives few properties associated with this analysis.

build/run/run-cmdline-client \
  (1)       -e http://www.ebi.ac.uk/soaplab/services/edit.seqret \
  (2)       -name edit.seqret \
  (3)       -ii \
  (4)       -oo

now (3) and (4) show not only names but also types and other input data properties.

This example uses Soaplab2 API for getting available service categories from the EBI Soaplab server, and also retrieves an example Uniprot entry using the seqret Web Service:

    static SoaplabBaseClient getClient(String endpoint) {
        ServiceLocator locator = new ServiceLocator();
        locator.setProtocol(ClientConfig.PROTOCOL_AXIS1);
        locator.setServiceEndpoint(endpoint);
        try {
            return new SoaplabBaseClient(locator);
        } catch (SoaplabException e) {
            e.printStackTrace();
            System.exit(1);
        }
        return null;
    }
 
    static void printCategories() {
        SoaplabBaseClient client = getClient("http://www.ebi.ac.uk/soaplab/services");
        String[] catgs = client.getAvailableCategories();
        for (String category : catgs) {
            System.out.println(" - " + category);
        }
    }
 
    public static void main(String[] arg) {
        printCategories();
        SoaplabBaseClient client = getClient("http://www.ebi.ac.uk/soaplab/services/edit.seqret");
        Map<String, Object> inputs = new HashMap<String, Object>();
        inputs.put("sequence_usa", "uniprot:p12345");
        try {
            SoaplabMap results = client.runAndWaitFor(SoaplabMap
                    .fromMap(inputs));
            Map<String, Object> outputs = SoaplabMap.toMap(results);
            System.out.println("sequence retrieved: " + outputs.get("outseq"));
        } catch (SoaplabException e) {
            e.printStackTrace();
        }
    }

The following example Perl script demonstrates use of the EBI Soaplab Web Services and the typed interface. It first calls the stretcher Web Service to calculate an optimal global alignment of two input sequences and then calls the plotcon Web Service to draw a plot of the sequence conservation within windows over the alignment.

#!/usr/bin/perl
use XML::Compile::WSDL11;
use XML::Compile::Transport::SOAPHTTP;
use strict;
 
my ( $seqid1, $seqid2 ) = @ARGV;
$seqid1 = 'uniprot:hba_human' unless $seqid1;
$seqid2 = 'uniprot:hbb_human' unless $seqid2;
 
my $serviceendpoint = 'http://www.ebi.ac.uk/soaplab/typed/services/';
 
my $runAndWaitFor =
  &getWebMethod( $serviceendpoint . 'alignment_global.stretcher' );
 
print "Calling the stretcher service and getting the response\n";
my ( $answer, $trace ) = $runAndWaitFor->(|>
	asequence       => { usa => $seqid1 },
	bsequence       => { usa => $seqid2 },
	aformat_outfile => 'msf'
);
 
my %answer_   = &getResponse($answer);
my $alignment = $answer_{"outfile"};
 
open( OUT, "> alignment.msf" );
print OUT $alignment;
close(OUT);
 
$runAndWaitFor =
  &getWebMethod( $serviceendpoint . 'alignment_multiple.plotcon' );
print "Calling the plotcon service and getting the response\n";
my ( $answer, $trace ) =
  $runAndWaitFor->(|> sequences => { direct_data => $alignment } );
 
%answer_ = &getResponse($answer);
my $graph = $answer_{"Graphics_in_PNG"};
 
my $i = 1;
foreach my $grph (@$graph) {
	open( OUT, "> plotcon$i.png" );
	foreach my $b ($grph) {
		print OUT $b;
	}
	close(OUT);
	$i++;
}
 
sub getResponse($) {
	my $answer          = shift;
	my %answer          = %{$answer};
	my %answer_         = %{ $answer{"runAndWaitForResponse"} };
	my $detailed_status = $answer_{"detailed_status"};
	if ( $detailed_status != 0 ) {
		my $report = $answer_{"report"};
		print "Service call didn't return normally:\n" . $report;
		exit 1;
	}
	return %answer_;
}
 
sub getWebMethod($) {
	my $endpoint = shift;
	print "Retriving and processing the WSDL\n";
	my $wsdl  = XML::LibXML->new->parse_file( $endpoint . '?wsdl' );
	my $proxy = XML::Compile::WSDL11->new($wsdl);
	print "Retriving and processing the XSDs\n";
	foreach my $schema ( 1, 2, 3 ) {
		my $xsdXml =
		  XML::LibXML->new->parse_file( $endpoint . '?xsd=' . $schema );
		$proxy->schemas->importDefinitions($xsdXml);
	}
	print "Generating a request message based on the WSDL\n";
	my $runAndWaitFor = $proxy->compileClient('runAndWaitFor');
}