EMBL-EBI Web Services

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== XML::Compile::SOAP ======

===== Installation =====

The XML::Compile::SOAP modules can be installed by:
  - Using CPAN to install XML::Compile::SOAP ([[http://search.cpan.org/perldoc?XML::Compile::SOAP|CPAN]]).
  - Downloading the XML::Compile::SOAP distribution and installing manually:
    * from [[http://search.cpan.org/perldoc?XML::Compile::SOAP|CPAN]]
    * from http://perl.overmeer.net/xml-compile/
For an overview of the how to install a module see [[..:module_install|Installing Perl Modules]].

**Note**: XML::Compile::SOAP ([[http://search.cpan.org/perldoc?XML::Compile::SOAP|CPAN]]) requires XML::LibXML ([[http://search.cpan.org/perldoc?XML::LibXML|CPAN]]) which uses the [[http://xmlsoft.org/|libxml2]] library, depending on your system you may have to install this separately.

===== Complex Types =====

In Document/literal SOAP services all messages are described using complex types. Thus to use any operation on a document/literal service the message has to be defined. In XML::Compile::SOAP ([[http://search.cpan.org/perldoc?XML::Compile::SOAP|CPAN]]) the message data is represented as a nested hash, which is mapped into the actual XML to be sent by XML::Compile ([[http://search.cpan.org/perldoc?XML::Compile|CPAN]]) using the XML schema information provided in the WSDL or imported separately.

For example the data structure passed to the ''getNumberOfResults(domain, query)'' operation of the [[:services:EB-eye]] service looks like:
<code perl>
(
	'parameters' => { # Message name. For document/literal wrapped this is always 'parameters'.
		'domain' => $domain,  # 'domain' parameter
		'query'  => $query,   # 'query' parameter
	}
);
</code>

More complex messages use nested parameters, for example:
  * Message structure for submission of a job to the [[:soaplab:overview|Soaplab]] seqret service: <code perl>
(
	'run' => { # Message name
		'sequence' => { # Sequence info.
			'usa' => 'embl:L12345' # Input sequence USA
		},
		'osformat_outseq'  => 'genbank' # Format to output
	}
);
</code>
  * Message structure to submit a job to the [[:services:sss:NCBI BLAST (SOAP)]] service, the special value ''NIL'' is used to indicate that the element should appear in the generated XML, but is undefined (''xsi:nil="true"''). For this service the ''interpret_nillable_as_optional'' option is set when compiling the operations so these elements are instead omitted from the generated XML: <code perl>
(
	'parameters' => { # Message name. For document/literal wrapped this is always 'parameters'.
		'email'      => $email, # E-mail address.
		'title'      => $title, # Job title
		'parameters' => { # Job parameters
			'program' => 'blastp',               # Search "program"
			'database' => 'uniprotkb_swissprot', # Database to search
			'matrix' => 'NIL'                    # Scoring matrix to use
			'exp' => 'NIL',                      # E-value threshold
			'filter' => 'NIL',                   # Low complexity filter
			'align' => 'NIL',                    # Pairwise alignment format
			'scores' => 'NIL',                   # Number of scores
			'alignments' => 'NIL',               # Number of alignments
			'dropoff' => 'NIL',                  # Drop-off score
			'match_scores' => 'NIL',             # Match/miss-match scores
			'match' => 'NIL',                    # Match score
			'mismatch' => 'NIL',                 # Mismatch score
			'gapopen' => 'NIL',                  # Open gap penalty
			'gapext' => 'NIL',                   # Gap extension penalty
			'gapalign' => 'NIL',                 # Optimise gap alignments
			'stype' => 'protein',                # Sequence type 'protein' or 'dna'
			'seqrange' => 'NIL',                 # Query sub-sequence to use
			'sequence' => 'uniprot:wap_rat',     # Query sequence file or DB:ID
		}
	}
);
</code>

===== Dynamic Interface from a WSDL =====

The service proxy object, which is used to access the service operations, can be generated from a document/literal WSDL. For example using [[:services:eb-eye|EB-eye]] to get the identifiers in UniProtKB that contain the term "auxin" ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/XML-Compile-SOAP/ebeye_xmlcompile.pl|examples/SOAP/XML-Compile-SOAP/ebeye_xmlcompile.pl]]):
<code perl>
# XML::Compile::SOAP modules
use XML::Compile::SOAP11; # XML::Compile::SOAP 2.x
use XML::Compile::WSDL11;
use XML::Compile::Transport::SOAPHTTP;

# Chunk size for getting results
my $chunkSize = 50;
# Query details
my ( $domain, $query ) = ( 'uniprot', 'azurin' );

# EB-eye WSDL URL
my $WSDL = 'http://www.ebi.ac.uk/ebisearch/service.ebi?wsdl';
# Create service proxy for web service
my $wsdlXml = XML::LibXML->new->parse_file($WSDL);
my $soapSrv = XML::Compile::WSDL11->new($wsdlXml);
# Compile all service methods
my (%soapOps);
foreach my $soapOp ($soapSrv->operations) {
    # XML::Compile::SOAP 2.x
    if($XML::Compile::SOAP::VERSION > 1.99) {
        $soapOps{ $soapOp->name } = $soapSrv->compileClient($soapOp->name);
    }
    # XML::Compile::SOAP 0.7x
    else {
        $soapOps{ $soapOp->{operation} } =  $soapSrv->compileClient($soapOp->{operation});
    }
}

# First find out how many
my ( $response, $trace ) = $soapOps{'getNumberOfResults'}->(
	parameters => {
		'domain' => $domain,
		'query'  => $query,
	}
);
# Check for server/SOAP fault
if ( $response->{'Fault'} ) {
	die "Server fault: " . $response->{'Fault'}->{'faultstring'};
}

# Extact the number of entries from the structure returned
my $numEntries = $response->{'parameters'}->{'numberOfResults'};
print "$numEntries entries found for $query in $domain\n";

# Loop over results getting and printing each chunk.
for ( my $start = 0 ; $start < $numEntries ; $start += $chunkSize ) {
	# Get the chunk
	( $response, $trace ) = $soapOps{'getResultsIds'}->(
		parameters => {
			'domain' => $domain,
			'query'  => $query,
			'start'  => $start,
			'size'   => $chunkSize,
		}
	);
	# Check for server/SOAP fault
	if ( $response->{'Fault'} ) {
		die "Server fault: " . $response->{'Fault'}->{'faultstring'};
	}
	if ( defined( $response->{'parameters'}->{'arrayOfIds'}->{'string'} )
		&& scalar( $response->{'parameters'}->{'arrayOfIds'}->{'string'} ) > 0 )
	{
		foreach
		  my $id ( @{ $response->{'parameters'}->{'arrayOfIds'}->{'string'} } )
		{
			print $id, "\n";
		}
	}
}
</code>

=== Exercise 1: EB-eye with XML::Compile::SOAP ===

The EB-eye search engine (http://www.ebi.ac.uk/Tools/webservices/services/eb-eye) provides a method for searching a broad selection of the databases available at EMBL-EBI. As well a search functionality it also provides methods for exploring the data using links based on the cross-references present in the data.

Using the example EB-eye client ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/XML-Compile-SOAP/ebeye_xmlcompile.pl|examples/SOAP/XML-Compile-SOAP/ebeye_xmlcompile.pl]]) as a guide, use the EB-eye to find the number of entries in EMBL-Bank Coding Sequence (emblcds) which contain the term "CFTR".

Sample solution: [[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/solutions/SOAP/XML-Compile-SOAP/q1_ebeye_xmlcompile.pl|solutions/SOAP/XML-Compile-SOAP/q1_ebeye_xmlcompile.pl]]

=== Exercise 2: EB-eye meta-data ===

Like [[:services:dbfetch|WSDbfetch]] the [[:services:EB-eye]] web service provides methods to get details of the available search domains, the fields within the domains and details of cross-references.

Starting from the example EB-eye client ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/examples/SOAP/XML-Compile-SOAP/ebeye_xmlcompile.pl|examples/SOAP/XML-Compile-SOAP/ebeye_xmlcompile.pl]]) get the list of available domains (''listDomains()'') and the fields within these domains (''listFields(domain)'').

Sample solution: [[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Perl_Exercise/solutions/SOAP/XML-Compile-SOAP/q2_ebeye_xmlcompile.pl|solutions/SOAP/XML-Compile-SOAP/q2_ebeye_xmlcompile.pl]]

===== SOAP Message Trace =====

Each XML::Compile::SOAP service call returns a response and a trace object. The trace contains the details of the SOAP message. 
<code perl>
my ( $response, $trace ) = $soapOps{'getNumberOfResults'}->(
	parameters => {
		'domain' => $domain,
		'query'  => $query,
	}
);
# Output SOAP message details.
$trace->printTimings;
$trace->printRequest;
$trace->printResponse;
</code>

===== Sample Clients =====

Most SOAP Web Services at [[http://www.ebi.ac.uk/|EMBL-EBI]] have sample clients which provide command-line access to the service and example code. For Perl some of the clients are based on XML::Compile::SOAP.

==== Document/literal SOAP ====

^ Service ^ Sample client ^
| [[:services:EB-eye]] | [[http://www.ebi.ac.uk/Tools/webservices/download_clients/perl/xmlcompile/ebeye_xmlcompile.pl|ebeye_xmlcompile.pl]] |
| [[:services:sss:NCBI BLAST (SOAP)]] | [[http://www.ebi.ac.uk/Tools/webservices/download_clients/perl/xmlcompile/ncbiblast_xmlcompile.pl|ncbiblast_xmlcompile.pl]] |
| [[:services:pfa:iprscan_soap|InterProScan (SOAP)]] | [[http://www.ebi.ac.uk/Tools/webservices/download_clients/perl/xmlcompile/iprscan_xmlcompile.pl|iprscan_xmlcompile.pl]] |
| [[:services:dbfetch|WSDbfetch (SOAP)]] | [[http://www.ebi.ac.uk/Tools/webservices/download_clients/perl/xmlcompile/wsdbfetch_xmlcompile.pl|wsdbfetch_xmlcompile.pl]] |

\\
^ Up | [[..:..:Perl]] ^ Contents | [[..:..:..:00_Contents|Contents]] |
EMBL-EBI Web Services

EMBL-EBI

Services

Research

Training

Industry

About us
