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

raw_execute

 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>"

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