[MOBY-l] How to set up a MOBY Service

[mwilkinson at gene.pbi.nrc.ca]

Okay, this is a first stab at an overview of how to set up services.  As
Lukas (and others) work through this and we discover problems I will keep a
record of the Q&A's so that we have a nicely organized and usable document at
the end.  Here goes version 0.001...

You have to first decide what your input and output objects are:

(1)  Use the MOBY Central API to check if your object(s) & namespaces exist
        - $MOBY = MOBY::Central->new;
        - $MOBY->retrieveObjectNames
        - $MOBY->retrieveNamespaces
        -  retrieve its structure:  $MOBY->retrieveObject
(1a)  If it doesn't exist, which is more than likely right now, then you need
to design it
        - http://www.w3school.com has a (lengthy) tutorial on how to write
W3C schema (XSD)
        - look at the simple examples that are already in the database
        - create your schema and register it:  $MOBY->registerObject  or
->registerNamespace

2)  Decide what type of service you are providing, and check if it exists
        - $MOBY->retrieveServiceTypes
2a)  If it doesn't exist, then you need to think where it fits in the
ontology and register it
        - $MOBY->registerServiceType

3)  Now set up your service CGI.  Mine looks like this:

     #!/usr/bin/perl -w
     use SOAP::Transport::HTTP;
     use lib "/var/www/cgi-bin/";# the folder containing your
                                 # service module(s)
     use MOBY::LocalServices;    # use the specific module(s)

     my $x = new SOAP::Transport::HTTP::CGI;
     $x->dispatch_with(
        {
           'http://biomoby.org/#MarksTestSequenceRetrieve' => 'MOBY::LocalServices',
        });

     $x->handle;

Some explanation of the code above might be helpful, though in principle you
can copy/paste this as your CGI and with small mod's it will work.

Your services are written as subroutines in modules.  You need to "use" that
module (in my case, "LocalServices.pm").  Inside my module is a subroutine
called "sub MarksTestSequenceRetrieve".  When the CGI receives a SOAP
request, it will read it as a call to the URI:

http://biomoby.org/#YourSubroutineNameHere

The URI is biomoby.org because that is the way the WSDL document is created
at MOBY Central.  You have no control over this, but it could be
BioMonkeyFun.nuts and it would still arrive at your machine so it doesn't
really matter... it's a URI not a URL.

The important bit is what comes after the #.  This is the subroutine that is
called on your server.  Using the "dispatch_with" call of SOAP::Lite you are
able to map subroutines as belonging to a particular module; in my case I am
mapping the method call "MarksTestSequenceRetrieve" to the module
"MOBY::LocalServices" because that is the module that handles that subroutine
call.  You can make as many mappings as you need in this hash.

The module code itself is also entirely straightforward.  Have a look at my
code below:

==========================================================================

#!/usr/bin/perl -w

package MOBY::LocalServices;
use lib "/var/www/cgi-bin";
use strict;
use vars qw($AUTOLOAD @ISA);
@ISA = qw(SOAP::Server::Parameters);
# above line gives if you access to the SOM if you want it

sub MarksTestSequenceRetrieve {
 my $SOM = pop;  # I don't use this, but it might be useful to you
 my ($self, $data) = @_;

 # extract the objects either with an XML parser or
 # if you are brave... with a regexp
 # validate the object type and/or namespace
 # extract the bits you need (again, XMP parser or regexp)
 # run your manipulation of them, whatever your service actually is...
 # and prepare to send them back. for example
 # a simple retrieve service from a genbank Gi could look like

my $response;

# construct your object
$response .= "   <Sequence namespace='GenBank/GI' id='$gi'>\n";
$response .= "      <Length>$length</Length>\n";
$response .= "      <Seq>$SEQ</Seq>\n";
$response .= "   </Sequence>\n";

#put it in a MOBY envelope
my $responseFull = "
     <MOBY AuthURI='http://bioinfo.pbi.nrc.ca'>\n
          $response
     </MOBY>\n ";

#now make it soapy and base64 it so that it doesn't get parsed
# by SOAP at the client end
my $SOAPResponse = SOAP::Data->type('base64' => $responseFull);

# and return it as always
return  $SOAPResponse;

}

============================================================

And that's it!  Now you need to register your service with MOBY Central
    - $MOBY->registerService (blah blah blah)
    - the ServiceName parameter ***IS THE SUBROUTINE NAME***!!!!

and then try it out.

Let me know how you get on, and if you need me to phone you just say so.
I've likely missed some things in this description...

Cheers!

M