Index

NAME
SYNOPSIS
DESCRIPTION
AUTHORS
METHODS

Code Index:

package MOBY::Client::Central
EOF

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" | "cgi-async" | "cgi" | "moby-async" | "doc-literal" | "doc-literal-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 documentation

deregisterService

 Usage     :	$REG = $MOBY->deregisterService(%args)
 Function  :	deregister a registered MOBY Service
 Returns   :	MOBY::Registration object
 Args      :	serviceName => $serviceID, authURI => $authority

findService

 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" | "cgi" | "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      :	none

retrieveServiceNames

 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 object

retrieveNamespaces

 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 LSID

DUMP

 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 default

ObjLSID

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