Edward Kawas > MOBY > MOBY::Central

Download:
MOBY-1.15.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 1.13   Source  

NAME ^

MOBY::Central.pm - API for communicating with the MOBY Central registry

SYNOPSIS ^

REQUIRES MYSQL 3.23 or later!!!!

If you are a Perl user, you should be using the MOBY::Client:Central module to talk to MOBY-Central

If you need to connect directly, here is how it is done in perl 5.6 and 5.6.1. It wont work in Perl 5.8... sorry. Look how MOBY::Client::Cent does it if you want to use Perl 5.8

-------------------------------------- SERVER-SIDE

 use SOAP::Transport::HTTP;

 my $x = new SOAP::Transport::HTTP::CGI;
 # fill in your server path below...
 $x->dispatch_to('WWW_SERVER_PATH', 'MOBY::Central');
 $x->handle;

---------------------------------------

CLIENT-SIDE

 use SOAP::Lite +autodispatch => 
      proxy => 'http://moby.ucalgary.ca/moby/MOBY-Central.pl', # or whatever...
      on_fault => sub {
         my($soap, $res) = @_; 
         die ref $res ? $res->faultstring : $soap->transport->status, "\n";
      };

 my $NAMES_XML = MOBY::Central->retrieveObjectNames;
 print $NAMES_XML;
 # ... do something with the XML

----------------------------------------

DESCRIPTION ^

Used to do various transactions with MOBY-Central registry, including registering new Object and Service types, querying for these types, registering new Servers/Services, or queryiong for available services given certain input/output or service type constraints.

CONFIGURATION ^

This depends on a config file to get its database connection information. At a minimum this config file must have the following clause:

 [mobycentral]
 url = some.url 
 username = foo
 password = bar
 port = portnumber
 dbname = mobycentral

The space before and after the '=' is critical.

The end of a clause is indicated by a blank line.

Additional identically formatted clauses may be added for each of:

  [mobyobject]
  [mobynamespace]
  [mobyservice]
  [mobyrelationship]

if these ontologies are being served from a local database (via the OntologyServer module). These clauses will be read by the OntologyServer module if they are present, otherwise default connections will be made to the MOBY Central ontology server.

The config file must be readable by the webserver, and the webserver environment should include the following ENV variable:

$ENV{MOBY_CENTRAL_CONFIG} = /path/to/config/file.name

AUTHORS ^

Mark Wilkinson (markw@illuminae.com)

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

Registration XML Object ^

This is sent back to you for all registration and deregistration calls

 <MOBYRegistration>
   <success>$success</success>
   <id>$id</id>
   <message><![CDATA[$message]]></message>
 </MOBYRegistration>

success is a boolean indicating a successful or a failed registration

id is the deregistration ID of your registered object or service to use in a deregister call.

message will contain any additional information such as the reason for failure.

METHODS ^

new

 Title     :    new
 Usage     :    deprecated

registerObjectClass

The registerObjectClass call is:

Input XML :

        <registerObjectClass>
            <objectType>NewObjectType</objectType>
            <Description><![CDATA[
                    human readable description
                    of data type]]>
            </Description>
            <Relationship relationshipType="RelationshipOntologyTerm">
               <objectType articleName="SomeName">ExistingObjectType</objectType>
               ...
               ...
            </Relationship>
            ...
            ...
            <authURI>Your.URI.here</authURI>
            <contactEmail>You@your.address.com</contactEmail>
        </registerObjectClass>

Output XML :

...Registration Object...

deregisterObjectClass

Input XML :

 <deregisterObjectClass>
   <objectType>ObjectOntologyTerm</objectType>
 </deregisterObjectClass>

Ouptut XML :

...Registration Object...

registerServiceType

Input XML :

        <registerServiceType>
         <serviceType>NewServiceType</serviceType>
         <contactEmail>your_name@contact.address.com</contactEmail>
         <authURI>Your.URI.here</authURI>
         <Description>
           <![CDATA[ human description of service type here]]>
         </Description>
         <Relationship relationshipType="RelationshipOntologyTerm">
           <serviceType>ExistingServiceType</serviceType>
           <serviceType>ExistingServiceType</serviceType>
         </Relationship>
         <Relationship relationshipType="AnotherRelationship">
              ....
         </Relationship>
        </registerServiceType>

Output XML :

...Registration Object...

deregisterServiceType

Input XML :

        <deregisterServiceType>
          <serviceType>ServiceOntologyTerm</serviceType>
        </deregisterServiceType>

Ouptut XML :

...Registration Object...

registerNamespace

Input XML :

        <registerNamespace>
           <namespaceType>NewNamespaceHere</namespaceType>
           <contactEmail>your_name@contact.address.com</contactEmail>
           <authURI>Your.URI.here</authURI>
           <Description>
              <![CDATA[human readable description]]>
           </Description>
        </registerNamespace>

Output XML :

...Registration Object...

deregisterNamespace

Input XML :

        <deregisterNamespace>
           <namespaceType>MyNamespace</namespaceType>
        </deregisterNamespace>

Ouptut XML :

...Registration Object...

registerService

 Input XML :

      <registerService>
         <Category>moby</Category> <!-- one of 'moby', 'moby-async', 'doc-literal', 'doc-literal-async', 'cgi', 'cgi-async'; 'moby' and 'moby-async' are RPC encoded -->
         <serviceName>YourServiceNameHere</serviceName>
         <serviceType>TypeOntologyTerm</serviceType>
         <signatureURL>http://path.to/your/signature/RDF.rdf</sisgnatureURL>
         <servieLSID>urn:lsid:biomoby.org:serviceinstance:myservice:version</serviceLSID>
         <authURI>your.URI.here</authURI>
         <URL>http://URL.to.your/Service.script</URL>;
         <contactEmail>your_name@contact.address.com</contactEmail>
         <authoritativeService>1 | 0 </authoritativeService>
         <Description><![CDATA[
               human readable COMPREHENSIVE description of your service]]>
         </Description>
         <Input>
              <!-- zero or more Primary (Simple and/or Collection) articles -->
         </Input>
         <secondaryArticles>
              <!-- zero or more INPUT Secondary articles -->
         </secondaryArticles>
         <Output>
              <!-- zero or more Primary (Simple and/or Collection) articles --> 
         </Output>
      </registerService>

 Output XML :

   ...Registration Object...

 There are two forms of Primary articles:

An example of the use of each of these might be another BLAST service, where you provide the sequences that make up the Blast database as well as the sequence to Blast against it. The sequences used to construct the database might be passed as a Collection input article containing multiple Sequence Objects, while the sequence to Blast against it would be a Simple input article consisting of a single Sequence Object.

There is currently only one form of Secondary article:

Articles are, optionally, named using the articleName attribute. This might be used if, for example, the service requires named inputs. The order of non-named articles in a single Input or Output set MUST not be meaningful.

The XML structure of these articles is as follows:

registerServiceWSDL

 Title     :    NOT YET IMPLEMENTED
 Usage     :    

deregisterService

 Title     :    deregisterService
 Usage     :    $REG = $MOBY->deregisterService($inputXML)
 Function  :    deregister a Service
 Returns   :    $REG object 
 inputXML  :
        <deregisterService>
          <authURI>biomoby.org</authURI>
          <serviceName>MyFirstService</serviceName>
        </deregisterService>

 ouptutXML :  see Registration XML object

findService

 inputXML:
          <findService>
             <!--  Service Query Object -->
          </findService>

 ServiceQueryObject XML:

To query MOBY Central, you fill out the relevant elements of a Query Ojbect. These include the input and/or output data Classes (by name from the Class ontology), the Service-type (by name from the Service-type ontology), the authority (service provider URI), or any number of keywords that must appear in the service description.

In addition to the search parameters, there are two "flags" that can be set in the Query object:

The Query object structure is as follows:

 <inputObjects>
   <Input>
      <!-- one or more Simple or Collection Primary articles -->
   </Input>
 </inputObjects>
 <outputObjects>
    <Output>
       <!-- one or more Simple or Collection Primary articles -->
    </Output>
 </outputObjects>
 <authoritative>1</authoritative>
 <Category>moby</Category>
 <serviceType>ServiceTypeTerm</serviceType>
 <serviceName>ServiceName</serviceName>
 <authURI>http://desired.service.provider</authURI>;
 <signatureURL>http://location.of.document/signature.rdf</signatureURL>
 <expandObjects>1|0</expandObjects> 
 <expandServices>1|0</expandServices>
 <keywords>
 <keyword>something</keyword>
    ....
    ....
 </keywords>


 outputXML

 <Services>
  <Service authURI="authority.URI.here" serviceName="MyService" lsid="urn:lsid:authority.uri:serviceinstance:id">
        <serviceType lsid='urn:...'>Service_Ontology_Term</serviceType>
        <Protocol>moby</Protocol> <!-- or 'cgi' or 'soap' -->
        <authoritative>1</authoritative>
        <contactEmail>your@email.address</contactEmail>
        <URL>http://endpoint.of.service</URL>
        <Input>
                 <!-- one or more Simple and/or Collection Primary articles -->
        </Input>
        <Output>
                 <!-- one or more Simple and/or Collection Primary articles --> 
        </Output>
        <secondaryArticles>
                 <!-- one or more Secondary articles -->
        </secondaryArticles>
        <Description><![CDATA[free text description here]]></Description>
  </Service>
  ...  <!--  one or more Service blocks may be returned -->
  ...
  ...
</Services>

retrieveService

 Title     :    retrieveService
 Usage     :    $WSDL = $MOBY->retrieveService($inputXML)
 Function  :    get the WSDL descriptions for services with this service name
 Returns   :    XML (see below)
 Comment   :    the WSDL that you get back is invalid w.r.t. the object structure
                    It will always be so.
                    It should be used only to create stubs for the connection to the service.
 inputXML  :
        <retrieveService>
         <Service authURI="authority.uri.here" serviceName="myServ"/>
        <retrieveService>

 outputXML (by category):

     moby: <Service lsid='urn:lsid:...'><![CDATA[WSDL document here]]</Service>

retrieveResourceURLs

 Title     :    retrieveResourceURLs
 Usage     :    $urls = $MOBY->retrieveResourceURLs
 Function  :    to retrieve the location(s) of the RDF versions of the various
                MOBY-S Ontologies
 Args      :    none
 Returns   :    XML (see below).  The "name" attribute indicates which ontology
                is described by the URL (Service, Object, Namespace, ServiceInstance, Full),
                and the "url" attribute provides a URL that, when called with an
                HTTP GET, will return RDF-XML describing that ontology.
 XML       :
        <resourceURLs>
            <Resource name="Service" url="http://mobycentral.org/RESOURCES/MOBY-S/Services/>
            <Resource name="Object" url="..."/>
            <Resource name="Namespace" url="...X..."/>
            <Resource name="Namespace" url="...Y..."/>
        </resourceURLs>

retrieveServiceProviders

 Title     :    retrieveServiceProviders
 Usage     :    $uris = $MOBY->retrieveServiceProviders()
 Function  :    get the list of all provider's AuthURI's
 Returns   :    XML (see below)
 Args      :    none
 XML       :
        <serviceProviders>
           <serviceProvider name="authority.info.here"/>
                ...
                ...
        </serviceProviders>

retrieveServiceNames

 Title     :    retrieveServiceNames
 Usage     :    $names = $MOBY->retrieveServiceNames()
 Function  :    get a (redundant) list of all registered service names
                (N.B. NOT service types!)
 Returns   :    XML (see below)
 Args      :    none
 XML       :
        <serviceNames>
           <serviceName name="serviceName" authURI='authority.info.here' lsid = 'urn:lsid...'/>
                ...
                ...
        </serviceNames>

retrieveServiceTypes

 Title     :    retrieveServiceTypes
 Usage     :    $types = $MOBY->retrieveServiceTypes()
 Function  :    get the list of all registered service types
 Returns   :    XML (see below)
 Args      :    none
 XML       :
        <serviceTypes>
           <serviceType name="serviceTypeName" lsid="urn:lsid...">
                  <Description><![CDATA[free text description here]]></Description>
                  <contactEmail>your@email.here</contactEmail>
                  <authURI>authority.uri.here</authURI>
                  <ISA lsid="urn:lsid...">parentTypeName</ISA>  <!-- both empty for root Service! -->
           </serviceType>
                ...
                ...
        </serviceTypes>

retrieveRelationshipTypes

 Title     :    retrieveRelationshipTypes
 Usage     :    $types = $MOBY->retrieveRelationshipTypes($xml)
 Function  :    get the list of all registered relationship types in the given ontology
 Returns   :    XML (see below)
 Args      :    input XML (ontologies are 'object', 'service', 'namespace', 'relationship')

 Input XML :  <Ontology>OntologyName</Ontology>
 Output XML:
        <relationshipTypes>
           <relationshipType relationship="ontologyterm" authority="biomoby.org">
                  <Description><![CDATA[free text description here]]></Description>
           </relationshipType>
                ...
                ...
        </relationshipTypes>

retrieveObjectNames

 Title     :    retrieveObjectNames
 Usage     :    $names = $MOBY->retrieveObjectNames()
 Function  :    get the list of all registered Object types
 Returns   :    XML (see below)
 Args      :    none
 XML       :
        <objectNames>
           <Object name="objectName" lsid="urn:lsid:...">
                  <Description><![CDATA[free text description here]]></Description>
           </Object>
                ...
                ...
        </objectNames>

retrieveObjectDefinition

 Title     :    retrieveObjectDefinition
 Usage     :    $registerObjectXML = $MOBY->retrieveObjectDefinition($inputXML)
 Function  :    get the full description of an object, as registered
 Returns   :    see input XML for registerObjectClass
 Input XML :
         <retrieveObjectDefinition>
                         <obqjectType>ExistingObjectClassname</objectType>
                 </retrieveObjectDefinition>

 Ouptut XML :
        <retrieveObjectDefinition>
            <objectType lsid="urn:lsid:...">NewObjectType</objectType>
            <Description><![CDATA[
                    human readable description
                    of data type]]>
            </Description>
            <Relationship relationshipType="urn:lsid...">
               <objectType articleName="SomeName" lsid="urn:lsid...">ExistingObjectType</objectType>
            </Relationship>
            ...
            ...
            <authURI>owner.URI.here</authURI>
            <contactEmail>owner@their.address.com</contactEmail>
        </retrieveObjectDefinition>

retrieveNamespaces

 Title     :    retrieveNamespaces
 Usage     :    $ns = $MOBY->retrieveNamespaces()
 Function  :    get the list of all registered Object types
 Returns   :    XML (see below)
 Args      :    none
 XML       :
        <Namespaces>
           <Namespace name="namespace" lsid="urn:lsid:...">
                  <Description><![CDATA[free text description here]]></Description>
                  <contactEmail>email@address.here</contactEmail>
                  <authURI>authority.uri.here</authURI>
           </Namespace>
                ...
                ...
        </Namespaces>

retrieveObject

 NOT YET IMPLEMENTED
 Title     :    retrieveObject
 Usage     :    $objects = $MOBY->retrieveObject($inputXML)
 Function  :    get the object xsd
 Returns   :    XML (see below)
 Args      :    $name - object name (from ontology) or "all" to get all objects

 inputXML  :
        <retrieveObject>
         <objectType>ObjectType | all</objectType>
        </retrieveObject>

 outputXML       :
        <Objects>
           <Object name="namespace">
                  <Schema><XSD schema fragment here></Schema>
           </Object>
                ...
                ...
        </Objects>

Relationships

 Title     :    Relationships
 Usage     :    $ns = $MOBY->Relationships()
 Function  :    get the fist level of relationships for the given term
 Returns   :    output XML (see below)
 Args      :    Input XML (see below).  
 Notes     :    expandRelationships behaviour
                   - for ISA relationships means traverse to root/leaves
                   - for HAS and HASA means traverse ISA to root/leaves and
                     for each node in the ISA hierarchy return the HAS/HASA
                     relationship partners, where 'root' matches container objects
                     and 'leaves' matches contained objects.
                     Example: suppose a relationship "objA HAS objB",
                     a) if query is objectType=>objA, direction=>'root', relationship=>'HAS',
                        then objB is in result set
                     b) if query is objectType=>objB, direction=>'leaves', relationship=>'HAS',
                        then objA is in result set

 input XML :
        <Relationships>
           <objectType>$term</objectType>
           <expandRelationship>1|0</expandRelationship>
           <direction>root|leaves</direction>
           <relationshipType>$relationship_term</relationshipType>
           ... more relationship types
           ...
        </Relationships>
 OR
        <Relationships>
           <serviceType>$term</serviceType>
           <expandRelationship>1|0</expandRelationship>
           <direction>root|leaves</direction>
           <relationshipType>$relationship_term</relationshipType>
           ... more relationship types
           ...
        </Relationships>


 outputXML :
  <Relationships>
    <Relationship relationshipType="RelationshipOntologyTerm">
       <objectType lsid='urn:lsid...'>ExistingObjectType</objectType>
       <objectType lsid='urn:lsid...'>ExistingObjectType</objectType>
    </Relationship>
    <Relationship relationshipType="AnotherRelationshipTerm">
        ....
    </Relationship>
  </Relationships>

 OR

  <Relationships>    
    <Relationship relationshipType="RelationshipOntologyTerm">
       <serviceType lsid='urn:lsid...'>ExistingServiceType</serviceType>
       <serviceType lsid='urn:lsid...'>ExistingServiceType</serviceType>
    </Relationship>
    <Relationship relationshipType="AnotherRelationshipTerm">
        ....
    </Relationship>
  </Relationships>

DUMP_MySQL

 Title     :    DUMP_MySQL
 Usage     :    $SQL = $MOBY->DUMP_MySQL; ($central,$object,$service,$namespace,$relat) = @{$SQL};
 Function  :    return a mysql dump of each of the current MOBY Central databases
 Returns   :    an array of SQL strings that can be used to recreate the database locally
 Args      :    none

Internal Object Methods ^

_getValidServices

 Title     :    _getValidServices
 Usage     :    %valid = $MOBY->_getValidServices($sth_hash, $query, $max_return)
 Function  :    execute the query in $query to return a non-redundant list of matching services
 Returns   :    XML 
 Args      :    none

_getServiceWSDL

 Title     :    _getServiceWSDL
 Usage     :    @valid = $MOBY->_getValidServices($dbh, $sth_hash, $query)
 Function  :    execute the query in $query to return a non-redundant list of matching services
 Returns   :    list of response strings in wsdl
 Args      :    none

_getInputXSD

  name    : _getInputXSD($InputXML, $SecondaryXML)
  function: to get an XSD describing the input to a MOBY Service,
            e.g. to use in a WSDL document
  args    : (see _serviceListResponse code above for full details of XML)
           $InputXML - the <Input>...</Input> block of a findService
           response message

           $SecondaryXML - the <secondaryArticles>...<sescondaryArticles>
           fragment of a findService response message

  returns :  XSD fragment of XML (should not return an XML header!)
  notes   : the structure of an Input block is as follows:
           <Input>
              <!-- one or more Simple or Collection articles -->
           </Input>

           the structure of a secondaryArticle block is as follows:
           <sescondaryArticles>
              <!-- one or more Parameter blocks -->
           </secondaryArticles>

_getOuputXSD

  name    : _getOutputXSD($OutputXML)
  function: to get an XSD describing the output from a MOBY Service
            e.g. to use in a WSDL document
  args    : (see _serviceListResponse code above for full details)
           $InputXML - the <Input>...</Input> block of a findService
           response message

           $SecondaryXML - the <secondaryArticles>...<sescondaryArticles>
           fragment of a findService response message

  returns :  XSD fragment of XML (should not return an XML header!)
  notes   : the structure of an Output block is as follows:
           <Input>
              <!-- one or more Simple or Collection articles -->
           </Input>

WSDL_Templates

syntax highlighting: