MOBY::Client::Service - an object for communicating with MOBY Services
use MOBY::Client::Service;
my $Service = MOBY::Client::Service->new(service => $WSDL); my $result = $Service->execute(@args);
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.
Mark Wilkinson (markw@illuminae.com)
BioMOBY Project: http://www.biomoby.org
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...
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
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.
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''.
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 ('').
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.
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
Usage : $result = $Service->raw_execute(inputXML => "<../>") Function : execute the MOBY service using a raw MOBY input block Returns : whatever the Service provides as output Args : inputXML => "<moby:MOBY>.....</moby:MOBY>"
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>"
}
Usage : $name = $Service->methods() Function : retrieve all possible method calls for a given service Returns : listref of method names as strings Args : none
Usage : $name = $Service->serviceName() Function : get the name of the service Returns : string Args : none
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