MOBY::Central.pm - API for communicating with the MOBY Central registry
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
----------------------------------------
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.
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
Mark Wilkinson (markw@illuminae.com)
BioMOBY Project: http://www.biomoby.org
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.
Title : new Usage : deprecated
The registerObjectClass call is:
used to register a new object Class into the Class ontology
can envision this as simply registering a new node into the Class ontology graph, and creating the primary connections from that node.
MOBY, by default, supports three types of Class Relationships: ISA, HAS, and HASA (these are the relationship ontology terms)
Foo ISA bar is a straight inheritence, where all attributes of bar are guaranteed to be present in foo.
foo HAS bar is a container type, where bar is an object inside of foo in one or more copies.
foo HASA bar is a container type, where bar is an object inside of foo in one copy only
notice that, in a HAS and HASA relationships, it is necessary to indicate an article name for each contained object type. Thus, for example, you could have a sequence object that contained a String object with name "nucleotideSequence" and an Integer object with the name "sequenceLength".
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...
used to remove an Object Class from the Class ontology
this will not be successful until you respond positively to an email sent to the address that you provided when registering that object.
you may only deregister Classes that you yourself registered!
you may not deregister Object Classes that are being used as input or output by ANY service
you may not deregister Object Classes that are in a ISA or HASA relationship to any other Object Class.
<deregisterObjectClass> <objectType>ObjectOntologyTerm</objectType> </deregisterObjectClass>
Ouptut XML :
used to register a new node in the Service Ontology
the ISA ontology terms must exist or this registration will fail.
all parameters are required.
email must be valid for later deregistration or updates
<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>
used to deregister a Service term from the Service ontology
will fail if any services are instances of that Service Type
will fail if any Service Types inherit from that Service Type.
<deregisterServiceType> <serviceType>ServiceOntologyTerm</serviceType> </deregisterServiceType>
used to register a new Namespace in the Namespace controlled vocabulary
must provide a valid email address
<registerNamespace> <namespaceType>NewNamespaceHere</namespaceType> <contactEmail>your_name@contact.address.com</contactEmail> <authURI>Your.URI.here</authURI> <Description> <![CDATA[human readable description]]> </Description> </registerNamespace>
used to remove a Namespace from the controlled vocabulary
will fail if that namespace is being used by any services
you will recieve an email for confirmation of the deregistration
<deregisterNamespace> <namespaceType>MyNamespace</namespaceType> </deregisterNamespace>
all elements are required
a service must have at least one Input OR Output Object Class. Either Input or Output may be blank to represent "PUT" or "GET" services respectively
the contactEmail address must be valid, as it is used to authorize deregistrations and changes to the service you registered.
the "authoritativeService" tag is used to indicate whether or not the registered service is "authoritative" for that transformation. i.e. if anyone else were to perform the same transformation they would have to have obtained the information to do so from you. This is similar to, but not necessarily identical to, mirroring someone elses data, since the data in question may not exist prior to service invocation.
only Input Secondary articles are defined during registration; Output Secondary objects are entirely optional and may or may not be interpreted Client-side using their articleName tags.
Service Categories:
moby - for services that use the MOBY SOAP messaging format and object structure (i.e. the objects used in service transaction inherit from the root 'Object' Class in the MOBY Class ontology).
authURI - a URI representing your organization (e.g. yourdomain.com); no http-prefix, and no trailing path information is allowed.
serviceName - an arbitrary, but unique, name for your service within your authURI namespace
URL - the URL to a SOAP CGI server that can invoke a method as described by your serviceName
wsdl - for other SOAP services that do not use the MOBY messaging format. The other elements in the registration should be interpreted as follows:
URL - the URL from which a WSDL document describing your service can be retrieved by an HTTP GET call.
Comments about Input and Output for MOBY and non-MOBY services
in "moby" services, the input and output messaging structure is defined by the BioMOBY API, and the services use data Objects that are defined in the Class ontology as inheriting from the root "Object" Class.
For "wsdl" services, there is additional flexibility:
Similar to a "moby" service, your "wsdl" service must consume/produce named data types. These are represented as LSID's
YOU DO NOT NEED TO REGISTER THESE DATA TYPES in MOBY Central; it is up to you what your LSID's represent, and MOBY Central WILL NOT try to resolve them!
You may mix ontologies when describing your service - i.e. you may freely use any MOBY Object as your input or (XOR) your output and use a non-MOBY object (LSID) for the alternate so long as you follow the MOBY message structure for the parameter that uses the MOBY Object
You may register, for example, a service that consumes a non-MOBY data Class and outputs a MOBY data class, so long as you follow the MOBY Messaging format for the output data
You may register, for example, a service that consumes a MOBY data Class and outputs a non-MOBY data class, so long as you follow the MOBY Messaging format for the input data
NOTE: Nether of the cases above are considered MOBY services, and are therefore described in the category of "soap" service
secondaryArticles - not applicable; should be left out of message.
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:
Simple - the article consists of a single MOBY Object
Collection - the article consists of a collection ("bag") of MOBY Objects (not necessarily the same object type).
Their number/order is not relevant, nor predictable
If order is important to the service provider, then a collection should not be used, rather the collection should be broken into named Simple parameters. This may impose limitations on the the types of services that can be registered in MOBY Central. If it becomes a serious problem, a new Primary article type will be added in a future revision.
The use of more than one Class in a collection is difficult to interpret, though it is equally difficult to envision a service that would require this. It is purposely left losely defined since any given Service Instance can tighten up this definition during the registration process.
A collection may contain zero or more Objects of each of the Classes defined in the XML during Service Instance registration.
Each distinct Object Class only needs to be included once in the XML. Additional entries of that Class within the same Collection definition must be ignored.
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:
Secondary - the article may or may not be specifically configured by the client as Input, and may or may not be returned by the Service as output.
In the case of inputs, they are generally user-configurable immediately prior to service invocation.
During service invocation a Client must send all Secondary articles defined in the Service Instance, even if no value has been provided either as default, or Client-side.
Secondary articles that are considered "required" by the Service should be registered with a default value.
The Service may fail if an unacceptable value is passed for any 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:
Simple (note that the lsid attribute of the objectType and Namespace element need only be present in the article when it is present in a response document from MOBY Central such as the result of a findService call. These attributes are ignored by MOBY Central when they appear in input messages such as registerService)
<Simple articleName="NameOfArticle"> <objectType lsid='urn:lsid:...'>ObjectOntologyTerm</objectType> <Namespace lsid='urn:lsid:...'>NamespaceTerm</Namespace> <Namespace lsid='urn:lsid:...'>...</Namespace><!-- one or more... --> </Simple>
Collection note that articleName of the contained Simple objects is not required, and is ignored.
<Collection articleName="NameOfArticle"> <Simple>......</Simple> <!-- Simple parameter type structure --> <Simple>......</Simple> <!-- DIFFERENT Simple parameter type (used only when multiple Object Classes appear in a collection) --> </Collection>
Secondary
<Parameter articleName="NameOfArticle"> <datatype>Integer|Float|String|DateTime</datatype> <description><![CDATA[freetext description of purpose]]></description> <default>...</default> <!-- any/all of these --> <max>...</max> <!-- ... --> <min>...</min> <!-- ... --> <enum>...<enum> <!-- ... --> <enum>...<enum> <!-- ... --> </Parameter>
Title : NOT YET IMPLEMENTED Usage :
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
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.
MOBY Central finds all services which match the contents of the Query Object.
All elements are optional, however at least one must be present.
All elements present are considered as increasingly limiting on the search (i.e. "AND").
keywords are:
comma-delimited
sentence-fragments are enclosed in double-quotes
wildcard "*" is allowed in combination with keyword fragments and or sentence fragments (lone "*" is meaningless and ignored)
multiple keywords are considered joined by "AND".
In addition to the search parameters, there are two "flags" that can be set in the Query object:
expandServices: this flag will cause MOBY Central to traverse the Service ontology and discover services that are child types (more specific) than the Service-type you requested
e.g. you might request "alignment", and it would discover services such as "Blast", "Smith Waterman", "Needleman Wunsch"
expandObjects: this flag will cause MOBY Central to traverse the Class ontology to find services that operate not only on the Object Class you are querying, but also any parent types or sub-objects of that Object Class.
e.g. if you request services that work on AnnotatedSequence Objects this flag will also return services that work on Sequence objects, since AnnotatedSequence objects inherit from Sequence objects
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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
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
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
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>
Simple
<Simple articleName="NameOfArticle"> <objectType>ObjectOntologyTerm</objectType> <Namespace>NamespaceTerm</Namespace> <Namespace>...</Namespace><!-- one or more... --> </Simple>
<Parameter articleName="NameOfArticle"> <datatype>INT|FLOAT|STRING</datatype> <default>...</default> <!-- any/all of these --> <max>...</max> <!-- ... --> <min>...</min> <!-- ... --> <enum>...<enum> <!-- ... --> <enum>...<enum> <!-- ... --> </Parameter>
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>
2 POD Errors
The following errors were encountered while parsing the POD:
=cut found outside a pod block. Skipping to next block.
To install MOBY, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MOBY
CPAN shell
perl -MCPAN -e shell install MOBY
For more information on module installation, please visit the detailed CPAN module installation guide.