NAME
MOBY::Client::Central - a client side wrapper for MOBY Central
SYNOPSIS
use MOBY::Client::Central;
my $Central = MOBY::Client::Central->new();
my ($Services, $REG) = $Central->findService(
input =>[
[DNASequence => ['NCBI_gi', 'NCBI_Acc']],
],
expandObjects => 1
);
unless ($Services){
print "Service discovery failed with the following errror: ";
print $REG->message;
end
}
foreach my $SERVICE(@{$Services}){
print "Service Name: ", $SERVICE->name, "\n";
print "Service Provider: ", $SERVICE->authority,"\n";
}DESCRIPTION
Client side "wrapper" for communicating with the MOBY::Central registry.
Used to do various read-only transactions with MOBY-Central. Parses MOBY::Central XML output into Perlish lists, hashes, and objects. This should be sufficient for most or all MOBY Client activities written in Perl.
AUTHORS
Mark Wilkinson (markw@illuminae.com)
BioMOBY Project: http://www.biomoby.org
METHODS
new
Usage : my $MOBY = MOBY::Client::Central->new(Registries => \%regrefs)
Function : connect to one or more MOBY-Central
registries for searching
Returns : MOBY::Client::Central object
ENV & PROXY : you can set environment variables to change the defaults.
By default, a call to 'new' will initialize MOBY::Client::Central
to connect to the default MOBY Central registry. The location of
this registry can be determined by examining the redirect from:
http://biomoby.org/mobycentral
If you wish to chose another registry by default, or if you need
to set up additional connection details (e.g. PROXY) then you may
set the following environment variables to whatever you
require:
MOBY_SERVER (default http://moby.ucalgary.ca/moby/MOBY-Central.pl)
MOBY_URI (default http://moby.ucalgary.ca/MOBY/Central)
MOBY_PROXY (no default)
Args : user_agent - optional. The name of your software application
Registries - optional.
- takes the form
{$NAME1 => {
URL => $URL,
URI => $URI,
PROXY => $proxy_server},
$NAME2 => {
URL => $URL,
URI => $URI,
PROXY => $proxy_server},
}
- by default this becomes
{mobycentral => {
URL => 'http://moby.ucalgary.ca/moby/MOBY-Central.pl',
URI => 'http://moby.ucalgary.ca/MOBY/Central'}
}
Discussion: Each registry must have a different
NAME. If you have more than one
registry with the same NAME, only
one will be used. You can NAME them
however you please - this is for
internal reference only. You will
make subsequent calls on one or more
of these registries by NAME, or by
default on all registries.
Notes : BE CAREFUL WITH OBJECT/SERVICE
REGISTRATION!! YOU WILL REGISTER
IN EVERY MOBY-CENTRAL YOU HAVE
NAMED! If you do not host a MOBY::Central
database locally, or don't know
better,then don't use any arguments
at all, and everything should work registerObject a.k.a registerObjectClass
Usage : $REG = $MOBY->registerObject(%args)
Usage : $REG = $MOBY->registerObjectClass(%args)
Function : register a new type of MOBY Object
Returns : MOBY::Registration object
Args : objectType => "the name of the Object"
description => "a human-readable description of the object"
contactEmail => "your@email.address"
authURI => "URI of the registrar of this object"
Relationships => {
relationshipType1 => [
{object => Object1,
articleName => ArticleName1},
{object => Object2,
articleName => ArticleName2}
],
relationshipType2 => [
{object => Object3,
articleName => ArticleName3}
]
}deregisterObject a.k.a. deregisterObjectClass
Usage : $REG = $MOBY->deregisterObject(%args)
Usage : $REG = $MOBY->deregisterObjectClass(%args)
Function : deregister a MOBY Object
Returns : MOBY::Registration object
Args : objectType => $objectName (from Object ontology)registerServiceType
Usage : $REG = $MOBY->registerServiceType(%args)
Function : register a new MOBY Service type
Returns : MOBY::Registration object
Args : serviceType => $serviceType
description => "human readable description"
Relationships => {$relationshipType1 => \@services,
$relationshipType2 => \@services}
contactEmail => "your@email.address.here"
authURI => "your.authority.info"deregisterServiceType
Usage : $REG = $MOBY->deregisterServiceType(%args)
Function : deregister a deprecated MOBY Service Type
Returns : MOBY::Registration object
Args : serviceType => $serviceType (from ontology)registerNamespace
Usage : $REG = $MOBY->registerNamespace(%args)
Function : register a new Namespace
Returns : MOBY::Registration object
Args : namespaceType => $namespaceType (required)
authURI => your.authority.URI (required)
description => "human readable description of namespace" (required)
contactEmail => "your@address.here" (required)deregisterNamespace
Usage : $REG = $MOBY->deregisterNamespace(%args)
Function : deregister a deprecated MOBY Namespace
Returns : MOBY::Registration object
Args : namespaceType => $mynamespaceType (from ontology)registerService
Usage : $REG = $MOBY->registerService(%args)
Function : register a new MOBY Service instance
Returns : MOBY::Registration object
Common Required Args :
serviceName => $serviceName,
serviceType => $serviceType,
authURI => $authURI,
contactEmail => "your@mail.address",
description => $human_readable_description,
category => "moby" | "post" | "moby-async"
URL => $URL_TO_SERVICE (or URL to WSDL document for wsdl-type services)
input: listref; (articleName may be undef)
input =>[
[articleName1,[objType1 => \@namespaces]], # Simple
[articleName2, [[objType2 => \@namespaces]]], # collection of one object type
[articleName3,[[objType3 => \@namespaces],
[objType4 => \@namespaces]]] # collection of multiple object types
]
output: listref; (articleName may be undef)
output =>[
[articleName1,[objType1 => \@namespaces]], # Simple
[articleName2,[[objType2 => \@namespaces]]], # collection of one object type
[articleName3,[[objType3 => \@namespaces],
[objType4 => \@namespaces]]] # collection of multiple object types
]
secondary: hashref
secondary => {parametername1 => {
datatype => TYPE,
description => "cutoff value",
default => DEFAULT,
max => MAX,
min => MIN,
enum => [one, two]},
parametername2 => {
datatype => TYPE,
description => "e-value",
default => DEFAULT,
max => MAX,
min => MIN,
enum => [one, two]}
}registerServiceWSDL
Usage : Needs documentationderegisterService
Usage : $REG = $MOBY->deregisterService(%args)
Function : deregister a registered MOBY Service
Returns : MOBY::Registration object
Args : serviceName => $serviceID, authURI => $authorityfindService
Usage : ($ServiceInstances, $RegObject) = $MOBY->findService(%args)
Function : Find services that match certain search criterion
Returns : ON SUCCESS: arrayref of MOBY::Client::ServiceInstance objects, and undef
ON FAILURE: undef, and a MOBY::Registration object indicating the reason for failure
Args :
Registry => which registry do you want to search (optional)
serviceName => $serviceName, (optional)
serviceType => $serviceType, (optional)
authURI => $authURI, (optional)
authoritative => 1, (optional)
category => "moby" | "post" | "moby-async" (optional)
expandObjects => 1, (optional)
expandServices => 1, (optional)
URL => $URL_TO_SERVICE (optional)
keywords => [kw1, kw2, kw3] (optional)
input =>[ (optional)
[objType1 => [ns1, ns2...]], # Simple
[[objType2 => [ns3, ns4...]]], # collection of one object type
[[objType3 => [ns3, ns4...]],
[objType4 => [ns5, ns6...]]], # collection of multiple object types
]
output =>[ (optional)
[objType1 => [ns1, ns2...]], # Simple
[[objType2 => [ns3, ns4...]]], # collection of one object type
[[objType3 => [ns3, ns4...]],
[objType4 => [ns5, ns6...]]], # collection of multiple object types
]retrieveService
Usage : $WSDL = $MOBY->retrieveService($ServiceInstance)
Function : get the WSDL definition of the service with this name/authority URI
Returns : a WSDL string
Args : The ServiceInstance object for that service (from findService call)retrieveResourceURLs
Usage : $names = $MOBY->retrieveResourceURLs()
Function : get a hash of the URL's for each of the MOBY ontologies
Returns : hashref to the following hash
$names{Ontology} = [URL1, URL2,...]
Args : noneretrieveServiceNames
Usage : $names = $MOBY->retrieveServiceNames(%args)
Function : get a (redundant) list of all registered service names
(N.B. NOT service types!)
Returns : hashref to the following hash
$names{$AuthURI} = [serviceName_1, serviceName_2, serviceName3...]
Args : registry => $reg_name: name of registry you wish to retrieve from (optional)
as_lsid => $boolean: return service names as their corresponding LSID's (default off)retrieveServiceProviders
Usage : @URIs = $MOBY->retrieveServiceProviders([$reg_name])
Function : get the list of all provider's AuthURI's
Returns : list of service provider URI strings
Args : $reg_name: name of registry you wish to retrieve from (optional) retrieveServiceTypes
Usage : $types = $MOBY->retrieveServiceTypes(%args)
Function : get the list of all registered service types
Returns : hashref of $types{$type} = $definition
Args : registry => $reg_name: name of registry you wish to retrieve from (optional)
as_lsid => $boolean: return the $type as its corresponding LSID (defualt off)retrieveServiceTypesFull
Usage : $types = $MOBY->retrieveServiceTypesFull(%args)
Function : get all details of all service types
Returns : hashref of $types{$type} = {Description => "definition",
authURI => "authority.uri.here",
contactEmail => "email@addy.here",
ISA => "parentType", # possibly empty string ""
ISA_LSID => "urn:lsid...parentLSID"} # possibly empty string ""
Args : registry => $reg_name: name of registry you wish to retrieve from (optional)
as_lsid => $boolean: return the $type as its corresponding LSID (defualt off)retrieveObjectNames
Usage : $names = $MOBY->retrieveObjectNames(%args)
Function : get the list of all registered Object types
Returns : hashref of hash:
$names{$name} = $definition
Args : registry => $reg_name: name of registry you wish to retrieve from (optional)
as_lsid => $boolean: return $name as its correspnding LSID (optional default off)retrieveObjectDefinition
Usage : $DEF = $MOBY->retrieveObjectDefinition(objectType => $objectType)
Function : retrieve the $XML that was used to register an object and its relationships
Returns : hashref, identical to the hash sent during Object registration, plus
an additional XML hash key that contains the actual XML containing
the object definition as sent by MOBY Central (used for a visual
overview, rather than parsing all of the hash keys)
objectType => "the name of the Object"
objectLSID => "urn:lsid:..."
description => "a human-readable description of the object"
contactEmail => "your@email.address"
authURI => "URI of the registrar of this object"
Relationships => {
relationshipType1 => [
{object => Object1,
articleName => ArticleName1,
lsid => lsid1},
{object => Object2,
articleName => ArticleName2,
lsid => lsid2}
],
relationshipType2 => [
{object => Object3,
articleName => ArticleName3,
lsid => lsid3}
]
}
XML => <....XML of object registration.../>
Args : objectType => the name or LSID URI for an objectretrieveNamespaces
Usage : $ns = $MOBY->retrieveNamespaces(%args)
Function : get the list of all registered Namespace types
Returns : hashref of hash:
$ns{$namespace} = $definition
Args : registry => $reg_name: name of registry you wish to retrieve from (optional)
as_lsid => $boolean: retrieve $namespace as its corresponding LSID (default off)retrieveNamespacesFull
Usage : $ns = $MOBY->retrieveNamespaces(%args)
Function : get all details about all namespaces
Returns : hashref of hash:
$ns{$namespace} = {Definition => $definition,
authURI => $authority,
contactEmail => $email}
Args : registry => $reg_name: name of registry you wish to retrieve from (optional)
as_lsid => $boolean: retrieve $namespace as its corresponding LSID (default off)retrieveObject
Usage : $objects = $MOBY->retrieveObjectNames(%args)
Function : get the object xsd
Returns : hashref of hash:
$objects{$name} = $W3C_XML_Schema_string
Args : registry => $reg - name of MOBY Central you want to use (must pass undef otherwise)
objectType => $name - object name (from ontology) or undef to get all objects
as_lsid => $boolean - return $name as its corresponding LSID (default off)Relationships
Usage : $def = $MOBY->Relationships(%args)
Function : traverse and return the relationships in the ontology
Returns : hashref of
FOR SERVICES:
$hash{'isa'}=[{lsid => $lsid, term => 'termy'},...]
FOR OBJECTS:
$hash{relationship_type}=[{lsid => $lsid, articleName => 'thingy', term => 'termy'},...]
Args : EITHER serviceType => $term_or_lsid
OR objectType => $term_or_lsid
Relationships => \@relationship_types (optional, 'all' if parameter is missing)
Registry => $registry_name (optional)
expandRelationships => [1/0] (optional)
direction => ['root'/'leaves'] (optional)ISA
Usage : $def = $MOBY->ISA($class1, $class2)
Function : a pre-canned use of the Relationships function
to quickly get an answer to whether class1 ISA class2
Returns : Boolean
Args : $class1 - an Object ontology term or LSID
$class2 - an Object ontology term or LSIDDUMP
Usage : ($mobycentral, $mobyobject, $mobyservice, $mobynamespace, $mobyrelationship) = $MOBY->DUMP(['registry'])
Function : DUMP the mysql for the current MOBY Central database
Returns : text
Args : $reg - name of MOBY Central you want to use if not defaultObjLSID
LSID_CACHE
Usage : $lsid = $MOBY->LSID_CACHE($term, $lsid)
Function : get/set LSID from the cache
Returns : lsid as a scalar
Args : the term for which you have/want an lsid,
and optionally the lsid to set.ISA_CACHE
Usage : @lsids = $MOBY->ISA_CACHE($lsid, \@isas)
Function : get/set the ISA relationships in the cache
Returns : list of ISA relationships. The ISA list
is IN ORDER from, excluding the term itself, to
root Object. Base Object returns an empty list.
Args : The LSID for which you have/want the ISA parentage,
and optionally the parentage listref to set.
Note : WHAT COMES BACK ARE LSIDs!!!