NAME

MOBY::Client::Service - an object for communicating with MOBY Services

SYNOPSIS

use MOBY::Client::Service;

my $Service = MOBY::Client::Service->new(service => $WSDL);
my $result = $Service->execute(@args);

DESCRIPTION

Deals with all SOAPy rubbish required to communicate with a MOBY Service. The object is created using the WSDL file returned from a MOBY::Client::Central->retrieveService() call. The only useful method call in this module is "execute", which executes the service.

AUTHORS

Mark Wilkinson (markw@illuminae.com)

BioMOBY Project: http://www.biomoby.org

METHODS

new

Usage     :	$Service = MOBY::Client::Service->new(@args)
Function  :	create a service connection
Returns   :	MOBY::Client::Service object, undef if no wsdl.
Args      :	service : string ; required
                         a WSDL file defining a MOBY service
               uri     : string ; optional ; default NULL
                         if the URI of the soap call needs to be personalized
                         this should almost never happen...

execute

Usage     :	$result = $Service->execute(%args)
Function  :	execute the MOBY service
Returns   :	whatever the Service provides as output
Args      :	XMLinputlist => \@data
Comment   :    @data is a list of single invocation inputs; the XML goes between the
               <queryInput> tags of a servce invocation XML.
Each element of @data is itself a listref of [articleName, $XML].
               articleName may be undef if it isn't required.
               $XML is the actual XML of the Input object

Examples

There are several ways in which you can execute a service. You may wish to invoke the service on several objects, and get the response back in a single message. You may wish to pass in a collection of objects, which should be treated as a single entity. Or you may wish to pass in parameters, along with data. In each case, you're passing in

XMLinputlist => [ ARGS ]

The structure of @ARGS helps MOBY to figure out what you want.

Iterate over multiple Simples

To have the service iterate over multiple equivalent objects, and return all the results in a single message, use this syntax (ARGS = ([...], [...], ...). Here, the articleName of the input parameter is "input1":

$Service->execute(XMLinputlist => [ 
                      ['input1', '<Object namespace="blah" id="123"/>'],
                      ['input1', '<Object namespace="blah" id="234"/>']
                          ]);

This would invoke the service twice (in a single message) the first time with an object "123" and the second time with object "234".

Process a Collection

To pass in a Collection, you need this syntax (ARGS = [ '', [..., ..., ...] ]). Here, the articleName of the input is "input1".

$Service->execute(XMLinputlist => [
               ['input1', [
                   '<Object namespace="blah" id="123"/>',
                   '<Object namespace="blah" id="234"/>']
            ]);

This would invoke the service once with a collection of inputs that are not required to be named ('').

Process multiple Simple inputs

To pass in multiple inputs, to be considered neither a Collection nor sequentially evaluated, use this syntax (ARGS = [..., ..., ...]). Here, the service consumes two inputs with articleName input1 and input2

  $Service->execute(XMLinputlist => [
            [
             'input1', '<Object namespace="blah" id="123"/>',
             'input2', '<Object namespace="blah" id="234"/>',
            ]
		     ]);

This would cause a single invocation of a service.

Parameters

Finally, MOBY will recognize parameters by virtue of their having been declared when the service was registered. You need to specify the name correctly.

$Service->execute(XMLinputlist => [
               [
           'input1', '<Object namespace="blah" id="123"/>',
           'input2', '<Object namespace="blah" id="234"/>',
           'param1', '<Value>0.001</Value>',
           ]
            ]);

This would cause a single invocation of a service requiring two input parameters named "input1" and "input2", and a parameter named 'param1' with a value of 0.001

enumerated_execute

 Usage     :	$result = $Service->enumerated_execute(%args)
 Function  :	execute the MOBY service using self-enumerated inputs
 Returns   :	whatever the Service provides as output
 Args      :	Input => %data
 Comment   :    %data is a hash of single invocation inputs
                the structure of %data is:
				
				$data{$queryID} = {articleName => $inputXML1, # for simples and parameters
				                   articleNmae => [$inputXML2, $inputXML3], # for collections
								   }
                $inputXML is the actual XML of the Input object
				for example <Object namespace="NCBI_gi" id="163483"/>
				
 a full example might be:
				
 $data{invocation1} = {id_to_match => "<Object namespace="GO" id="0003875"/>",
                       id_list => ["<Object namespace="GO" id="0003875"/>,
					               "<Object namespace="GO" id="0009984"/>,...
								   ]
						cutoff => "<Value>10</Value>"
						}

methods

Usage     :	$name = $Service->methods()
Function  :	retrieve all possible method calls for a given service
Returns   :	listref of method names as strings
Args      :	none

serviceName

Usage     :	$name = $Service->serviceName()
Function  :    get the name of the service
Returns   :	string
Args      :	none

_getServiceName

 Usage     :	$name = $Service->_getServiceName()
 Function  :	Internal method to retrieve the name of the service from the SOAP object
                In the case of Asynchronous services it will return the base name of
		the service (i.e. myService, rather than myService_submit).  This base name
		is not guaranteed to give you any output if you call it!
 Returns   :	string
 Args      :	none