spacer
spacer

XML::Compile::SOAP

Installation

The XML::Compile::SOAP modules can be installed by:

  1. Using CPAN to install XML::Compile::SOAP (CPAN).
  2. Downloading the XML::Compile::SOAP distribution and installing manually:

For an overview of the how to install a module see Installing Perl Modules.

Note: XML::Compile::SOAP (CPAN) requires XML::LibXML (CPAN) which uses the 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 (CPAN) the message data is represented as a nested hash, which is mapped into the actual XML to be sent by 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 EB-eye service looks like:

(
	'parameters' => { # Message name. For document/literal wrapped this is always 'parameters'.
		'domain' => $domain,  # 'domain' parameter
		'query'  => $query,   # 'query' parameter
	}
);

More complex messages use nested parameters, for example:

  • Message structure for submission of a job to the Soaplab seqret service:
    (
    	'run' => { # Message name
    		'sequence' => { # Sequence info.
    			'usa' => 'embl:L12345' # Input sequence USA
    		},
    		'osformat_outseq'  => 'genbank' # Format to output
    	}
    );
  • Message structure to submit a job to the 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:
    (
    	'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
    		}
    	}
    );

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 EB-eye to get the identifiers in UniProtKB that contain the term “auxin” (examples/SOAP/XML-Compile-SOAP/ebeye_xmlcompile.pl):

# 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";
		}
	}
}

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 (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: solutions/SOAP/XML-Compile-SOAP/q1_ebeye_xmlcompile.pl

Exercise 2: EB-eye meta-data

Like WSDbfetch the 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 (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: 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.

my ( $response, $trace ) = $soapOps{'getNumberOfResults'}->(
	parameters => {
		'domain' => $domain,
		'query'  => $query,
	}
);
# Output SOAP message details.
$trace->printTimings;
$trace->printRequest;
$trace->printResponse;

Sample Clients

Most SOAP Web Services at 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

 
tutorials/06_programming/perl/soap/xml-compile-soap.txt · Last modified: 2012/09/17 13:54 by hpm
spacer
spacer