[MOBY-guts] biomoby commit
Mark Wilkinson
mwilkinson at pub.open-bio.org
Wed Apr 14 20:10:35 UTC 2004
mwilkinson
Wed Apr 14 16:10:35 EDT 2004
Update of /home/repository/moby/moby-live/Perl/MOBY
In directory pub.open-bio.org:/tmp/cvs-serv13487/MOBY
Modified Files:
CommonSubs.html CommonSubs.pm
Log Message:
updating docs and HTML docs
moby-live/Perl/MOBY CommonSubs.html,1.8,1.9 CommonSubs.pm,1.44,1.45
===================================================================
RCS file: /home/repository/moby/moby-live/Perl/MOBY/CommonSubs.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- /home/repository/moby/moby-live/Perl/MOBY/CommonSubs.html 2003/12/27 20:24:52 1.8
+++ /home/repository/moby/moby-live/Perl/MOBY/CommonSubs.html 2004/04/14 20:10:35 1.9
@@ -15,9 +15,9 @@
<ul>
<li><a href="#name">NAME</a></li>
- <li><a href="#client_side_paradigm">Client Side Paradigm</a></li>
<ul>
+ <li><a href="#client_side_paradigm">Client Side Paradigm</a></li>
<li><a href="#serviceside_paradigm">Service-Side Paradigm</a></li>
</ul>
@@ -27,6 +27,10 @@
<li><a href="#methods">METHODS</a></li>
<ul>
+ <li><a href="#genericserviceinputparser">genericServiceInputParser</a></li>
+ <li><a href="#complexserviceinputparser">complexServiceInputParser</a></li>
+ <li><a href="#getarticles">getArticles</a></li>
+ <li><a href="#genericserviceinputparserasobject">genericServiceInputParserAsObject</a></li>
<li><a href="#getsimplearticleids">getSimpleArticleIDs</a></li>
<li><a href="#getsimplearticlenamespaceuri">getSimpleArticleNamespaceURI</a></li>
<li><a href="#simpleresponse">simpleResponse</a></li>
@@ -35,18 +39,21 @@
<li><a href="#responsefooter">responseFooter</a></li>
<li><a href="#getinputs">getInputs</a></li>
<li><a href="#getinputid">getInputID</a></li>
- <li><a href="#getarticles">getArticles</a></li>
+ <li><a href="#getarticlesasobjects">getArticlesAsObjects</a></li>
<li><a href="#getcollectedsimples">getCollectedSimples</a></li>
<li><a href="#getinputarticles">getInputArticles</a></li>
<li><a href="#issimplearticle">isSimpleArticle</a></li>
<li><a href="#iscollectionarticle">isCollectionArticle</a></li>
- <li><a href="#getnodecontentwitharticle">getNodeContentWithArticle</a></li>
+ <li><a href="#issecondaryarticle">isSecondaryArticle</a></li>
<li><a href="#extractrawcontent">extractRawContent</a></li>
+ <li><a href="#getnodecontentwitharticle">getNodeContentWithArticle</a></li>
<li><a href="#validatenamespaces">validateNamespaces</a></li>
<li><a href="#validatethisnamespace">validateThisNamespace</a></li>
<li><a href="#getresponsearticles__a_k_a__extractresponsearticles_">getResponseArticles (a.k.a. extractResponseArticles)</a></li>
+ <li><a href="#getservicenotes">getServiceNotes</a></li>
<li><a href="#getcrossreferences">getCrossReferences</a></li>
<li><a href="#whichdeepestparentobject">whichDeepestParentObject</a></li>
+ <li><a href="#_rearrange__stolen_from_bioperl_____">_rearrange (stolen from BioPerl ;-) )</a></li>
</ul>
</ul>
@@ -61,57 +68,55 @@
MOBY Services</p>
<p>
</p>
-<hr />
-<h1><a name="client_side_paradigm">Client Side Paradigm</a></h1>
+<h2><a name="client_side_paradigm">Client Side Paradigm</a></h2>
+<p>not written yet</p>
<p>
</p>
<h2><a name="serviceside_paradigm">Service-Side Paradigm</a></h2>
<p>The following is a generalized architecture for *all*
-BioMOBY services showing how to parse incoming messages...</p>
+BioMOBY services showing how to parse incoming messages
+using the subroutines provided in CommonSubs</p>
<pre>
sub myServiceName {
- my ($caller, $message) = @_; # get the incoming MOBY query XML</pre>
-<pre>
- my @queries = getInputs($message); # returns XML::DOM nodes
- my $MOBY_RESPONSE = ""; # set empty response
-
- foreach my $query(@queries){</pre>
-<pre>
- my $queryID = getInputID($query); # get the queryID attribute of the queryInput
-
- my @input_articles = getArticles($query); # get the Simple/Collection articles making up this query
- foreach my $input(@input_articles){ # input is a listref</pre>
-<pre>
- my ($articleName, $article) = @{$input}; # get the named article
-
- my $simple = isSimpleArticle($article); # articles may be simple or collection
- my $collection = isCollectionArticle($article);</pre>
-<pre>
- if ($collection){</pre>
-<pre>
- # do something wtih the collection...
- # for example...
- my @simples = getCollectedSimples($article);
- # blah blah blah...
-
- } elsif ($simple){
- # maybe you just need the ID of the incoming query:
- my ($id) = getSimpleArticleIDs('NCBI_gi', $article); # if you need the ID</pre>
-<pre>
- # or maybe you are going to do something with the content?
- # for example, this will get the array of text lines
- # for the moby:String object with the articleName 'SequenceString'
- # that is in this $article
- my @sequence = getNodeContentWithArticle($article, "String", "SequenceString");</pre>
-<pre>
- # DO YOUR ANALYSIS HERE
- my $result = ""; #whatever you analysis says
-
- $MOBY_RESPONSE .= simpleResponse($result, "outputArticlename", $queryID);
+ my ($caller, $data) = @_;
+ my $MOBY_RESPONSE; # holds the response raw XML
+
+ # genericServiceInputParser
+ # unpacks incoming message into an array of arrarefs.
+ # Each element of the array is a queryInput block, or a mobyData block
+ # the arrayref has the following structure:
+ # [SIMPLE, $queryID, $simple]
+ # the first element is a constant "SIMPLE" or "COLLECTION"
+ # the second element is the queryID (required for enumerating the responses)
+ # the third element is the XML::DOM for the Simple or Collection block
+ my (@inputs)= genericServiceInputParser($data);
+ # or fail properly with an empty response
+ return SOAP::Data->type('base64' => responseHeader("my.authURI.com") . responseFooter()) unless (scalar(@inputs));
+
+ # you only need to do this if you are intending to be namespace aware
+ # some services might not care what namespace the data is in, so long
+ # as there is data...
+ my @validNS_LSID = validateNamespaces("NCBI_gi"); # returns LSID's for each human-readable</pre>
+<pre>
+ foreach (@inputs){
+ my ($articleType, $qID, $input) = @{$_};
+ unless (($articleType == SIMPLE) && ($input)){
+ # in this example, we are only accepting SIMPLE types as input
+ # so write back an empty response block and move on to the next
+ $MOBY_RESPONSE .= simpleResponse("", "", $qID) ;
+ next;
+ } else {
+ # now take the namespace and ID from our input article
+ # (see pod docs for other possibilities)
+ my $namespace = getSimpleArticleNamespaceURI($input); # get namespace
+ my ($identifier) = getSimpleArticleIDs($input); # get ID (note array output! see pod)
+
+ # here is where you do whatever manipulation you need to do
+ # for your particular service.
+ # you will be building an XML document into $MOBY_RESPONSE
}
- }
- }
- return responseHeader("my.authURI.com") . $MOBY_RESPONSE . responseFooter;
+ }
+ return SOAP::Data->type('base64' => (responseHeader("illuminae.com") . $MOBY_RESPONSE . responseFooter));
}</pre>
<p>
</p>
@@ -119,45 +124,62 @@
<h1><a name="example">EXAMPLE</a></h1>
<p>A COMPLETE EXAMPLE OF AN EASY MOBY SERVICE</p>
<p>This is a service that:</p>
-<p>CONSUMES: Object in the NCBI_Acc namespace
-EXECUTES: Retrieval
-PRODUCES: GenericSequence (in the NCBI_Acc namespace)</p>
<pre>
- use Bio::Perl;
-
+ CONSUMES: base Object in the GO namespace
+ EXECUTES: Retrieval
+ PRODUCES: GO_Term (in the GO namespace)</pre>
+<pre>
# this subroutine is called from your dispatch_with line
- # in your SOAP daemon
-
- sub myServiceName {
- my ($caller, $message) = @_; # get the incoming MOBY query XML</pre>
+ # in your SOAP daemon</pre>
<pre>
- my @queries = getInputs($message); # returns XML::DOM nodes
- my $MOBY_RESPONSE = ""; # set empty response
-
- foreach my $query(@queries){</pre>
-<pre>
- my $queryID = getInputID($query); # get the queryID attribute of the queryInput
-
- my @input_articles = getArticles($query); # get the Simple/Collection articles making up this query
- foreach my $input(@input_articles){ # input is a listref
- my ($articleName, $article) = @{$input}; # get the named article
- next unless isSimpleArticle($article); # I only allow simple inputs in my service signature
- my ($id) = getSimpleArticleIDs('NCBI_Acc', $article); # if you need the ID
- my $seq;
- eval {$seq = get_sequence('genbank',$id);} # suppress bioperl error messages
- my $response = "";
- if ($seq){
- $length = length($seq);
- $response = "<GenericSequence namespace='NCBI_Acc' id='$id'>
- <Integer namespace='' id='' articleName='Length'>$length</Integer>
- <String namespace='' id='' articleName='SequenceString'>$seq</String>
- </GenericSequence>";
- }
- $MOBY_RESPONSE .= simpleResponse($response, '', $queryID);
+ sub getGoTerm {
+ my ($caller, $message) = @_;
+ my $MOBY_RESPONSE;
+ my (@inputs)= genericServiceInputParser($message); # ([SIMPLE, $queryID, $simple],...)
+ return SOAP::Data->type('base64' => responseHeader('my.authURI.com') . responseFooter()) unless (scalar(@inputs));</pre>
+<pre>
+ my @validNS = validateNamespaces("GO"); # ONLY do this if you are intending to be namespace aware!</pre>
+<pre>
+ my $dbh = _connectToGoDatabase();
+ return SOAP::Data->type('base64' => responseHeader('my.authURI.com') . responseFooter()) unless $dbh;
+ my $sth = $dbh->prepare(q{
+ select name, term_definition
+ from term, term_definition
+ where term.id = term_definition.term_id
+ and acc=?});</pre>
+<pre>
+ foreach (@inputs){
+ my ($articleType, $ID, $input) = @{$_};
+ unless ($articleType == SIMPLE){
+ $MOBY_RESPONSE .= simpleResponse("", "", $ID);
+ next;
+ } else {
+ my $ns = getSimpleArticleNamespaceURI($input);
+ (($MOBY_RESPONSE .= simpleResponse("", "", $ID)) && (next))
+ unless validateThisNamespace($ns, @validNS); # only do this if you are truly validating namespaces
+ my ($accession) = defined(getSimpleArticleIDs($ns, [$input]))?getSimpleArticleIDs($ns,[$input]):undef;
+ unless (defined($accession)){
+ $MOBY_RESPONSE .= simpleResponse("", "", $ID);
+ next;
+ }
+ unless ($accession =~/^GO:/){
+ $accession = "GO:$accession"; # we still haven't decided on whether id's should include the prefix...
+ }
+ $sth->execute($accession);
+ my ($term, $def) = $sth->fetchrow_array;
+ if ($term){
+ $MOBY_RESPONSE .= simpleResponse("
+ <moby:GO_Term namespace='GO' id='$accession'>
+ <moby:String namespace='' id='' articleName='Term'>$term</moby:String>
+ <moby:String namespace='' id='' articleName='Definition'>$def</moby:String>
+ </moby:GO_Term>", "GO_Term_From_ID", $ID)
+ } else {
+ $MOBY_RESPONSE .= simpleResponse("", "", $ID)
+ }
}
- }
- }
- return responseHeader("my.authURI.com") . $MOBY_RESPONSE . responseFooter;
+ }
+
+ return SOAP::Data->type('base64' => (responseHeader("my.authURI.com") . $MOBY_RESPONSE . responseFooter));
}</pre>
<p>
</p>
@@ -166,7 +188,8 @@
<p>CommonSubs are used to do various manipulations of MOBY Messages. It is useful
both Client and Service side to construct and parse MOBY Messages, and ensure
that the message structure is valid as per the API.</p>
-<p>It DOES NOT connect to MOBY Central for any of its functions.</p>
+<p>It DOES NOT connect to MOBY Central for any of its functions, though it does
+contact the ontology server, so it will require a network connection.</p>
<p>
</p>
<hr />
@@ -179,6 +202,150 @@
<h1><a name="methods">METHODS</a></h1>
<p>
</p>
+<h2><a name="genericserviceinputparser">genericServiceInputParser</a></h2>
+<pre>
+ name : genericServiceInputParser
+ function : For the MOST SIMPLE SERVICES that take single Simple or Collection inputs
+ and no Secondaries this routine takes the MOBY message and
+ breaks the objects out of it in a useful way
+ usage : my @inputs = genericServiceInputParser($MOBY_mssage));
+ args : $message - this is the SOAP payload; i.e. the XML document containing the MOBY message
+ returns : @inputs - the structure of @inputs is a list of listrefs.
+ Each listref has three components:
+ 1. COLLECTION|SIMPLE|SECONDARY (i.e. constants 1, 2, 3)
+ 2. queryID (undef for Secondary parameters)
+ 3. $data - the data takes several forms
+ a. $article XML::DOM node for Simples
+ <queryInput...>...</queryInput>
+ b. \@article XML:DOM nodes for Collections
+ c. $secondary XML::DOM node</pre>
+<p>
+</p>
+<h2><a name="complexserviceinputparser">complexServiceInputParser</a></h2>
+<pre>
+ name : complexServiceInputParser
+ function : For more complex services taht have multiple articles for each input
+ and/or accept parameters, this routine will take a MOBY message and
+ extract the Simple/Collection/Parameter objects out of it in a
+ useful way.
+ usage : my $inputs = complexServiceInputParser($MOBY_mssage));
+ args : $message - this is the SOAP payload; i.e. the XML document containing the MOBY message
+ returns : $inputs is a hashref with the following structure:
+
+ $inputs->{$queryID} = [ [TYPE, $DOM], [TYPE, $DOM], [TYPE, $DOM] ]
+
+ Simples ------------------------
+
+ for example, the input message:
+
+ <queryInput queryID = '1'>
+ <Simple articleName='name1'>
+ <Object namespace=blah id=blah/>
+ </Simple>
+ <Parameter articleName='cutoff'>
+ <datatype>Float</datatype>
+ <default>10</default>
+ </Parameter>
+ </queryInput></pre>
+<pre>
+ will become:
+ (note that SIMPLE, COLLECTION, and SECONDARY are exported constants from this module)
+
+ $inputs->{1} = [ [SIMPLE, $DOM_name1],
+ [SECONDARY, $DOM_cutoff]
+ ]</pre>
+<pre>
+ Please see the XML::DOM pod documentation for information about how
+ to parse XML DOM objects.
+
+
+ Collections --------------------
+
+ With inputs that have collections these are presented as a
+ listref of Simple article DOM's. So for the following message:
+
+ <queryInput>
+ <Collection articleName='name1'>
+ <Simple>
+ <Object namespace=blah id=blah/>
+ </Simple>
+ <Simple>
+ <Object namespace=blah id=blah/>
+ </Simple>
+ </Collection>
+ <Parameter articleName='cutoff'>
+ <datatype>Float</datatype>
+ <default>10</default>
+ </Parameter>
+ </queryInput></pre>
+<pre>
+ will become
+
+ $inputs->{1} = [ [COLLECTION, [$DOM, $DOM] ],
+ [SECONDARY, $DOM_cutoff]
+ ]</pre>
+<pre>
+ Please see the XML::DOM pod documentation for information about how
+ to parse XML DOM objects.</pre>
+<p>
+</p>
+<h2><a name="getarticles">getArticles</a></h2>
+<pre>
+ name : getArticles
+ function : get the Simple/Collection/Parameter articles for a single queryInput
+ or queryResponse node
+ usage : @articles = getArticles($XML)
+ args : raw XML or XML::DOM of a queryInput, mobyData, or queryResponse block (e.g. from getInputs)
+ returns : a list of listrefs; each listref is one component of the queryInput.
+ a single queryInput/Response may consist of one or more named or unnamed
+ simple, collection, or parameter articles.
+ The listref structure is thus [name, $ARTICLE_DOM]:
+
+ e.g.: @articles = ['name1', $SIMPLE_DOM]</pre>
+<pre>
+ generated from the following sample XML:</pre>
+<pre>
+ <queryInput>
+ <Simple articleName='name1'>
+ <Object namespace=blah id=blah/>
+ </Simple>
+ </queryInput>
+
+ or : @articles = ['name1', $COLL_DOM], ['paramname1', $PARAM_DOM]</pre>
+<pre>
+ generated from the following sample XML:</pre>
+<pre>
+ <queryInput>
+ <Collection articleName='name1'>
+ <Simple>
+ <Object namespace=blah id=blah/>
+ </Simple>
+ <Simple>
+ <Object namespace=blah id=blah/>
+ </Simple>
+ </Collection>
+ <Parameter articleName='e value cutoff'>
+ <datatype>Float</datatype>
+ <default>10</default>
+ </Parameter>
+ </queryInput></pre>
+<p>
+</p>
+<h2><a name="genericserviceinputparserasobject">genericServiceInputParserAsObject</a></h2>
+<pre>
+ name : DO NOT USE!
+ function : to take a MOBY message and break the objects out of it. This is identical
+ to the subroutine above, except that it returns the data as
+ Objects rather than XML::DOM nodes
+ usage : my @inputs = genericServiceInputParser($MOBY_mssage));
+ args : $message - this is the SOAP payload; i.e. the XML document containing the MOBY message
+ returns : @inputs - the structure of @inputs is a list of listrefs.
+ Each listref has three components:
+ 1. COLLECTION|SIMPLE|SECONDARY (i.e. constants 1, 2, 3)
+ 2. queryID (undef for Secondary parameters)
+ 3. $data - either MOBY::Client::SimpleArticle, CollectionArticle, or SecondaryArticle</pre>
+<p>
+</p>
<h2><a name="getsimplearticleids">getSimpleArticleIDs</a></h2>
<pre>
name : getSimpleArticleIDs
@@ -243,12 +410,16 @@
</p>
<h2><a name="responseheader">responseHeader</a></h2>
<pre>
- name : responseHeader($auth)
- function : print the XML string of a MOBY response header
- usage : return responseHeader('illuminae.com') . $DATA . responseFooter;
- args : a string representing the service providers authority URI
- caveat : will soon be expanded to include service provision info
- and additional namespace declarations
+ name : responseHeader
+ function : print the XML string of a MOBY response header +/- serviceNotes
+ usage : responseHeader('illuminae.com')
+ responseHeader(
+ -authority => 'illuminae.com',
+ -note => 'here is some data from the service provider')
+ args : a string representing the service providers authority URI,
+ OR a set of named arguments with the authority and the
+ service provision notes.
+ caveat :
notes : returns everything required up to the response articles themselves.
i.e. something like:
<?xml version='1.0' encoding='UTF-8'?>
@@ -274,8 +445,8 @@
function : get the queryInput block(s) as XML::DOM nodes
usage : @queryInputs = getInputArticles($XML)
args : the raw XML of a <MOBY> query, or an XML::DOM document
- returns : a list of XML::DOM::Node's, each is a queryInput.
- Note : Remember that queryInputs are numbered! This is what you
+ returns : a list of XML::DOM::Node's, each is a queryInput or mobyData block.
+ Note : Remember that these blocks are enumerated! This is what you
pass as the third argument to the simpleResponse or collectionResponse
subroutine to associate the numbered input to the numbered response</pre>
<p>
@@ -285,40 +456,23 @@
name : getInputID
function : get the value of the queryID element
usage : @queryInputs = getInputID($XML)
- args : the raw XML or XML::DOM of a <queryInput> block
+ args : the raw XML or XML::DOM of a queryInput or mobyData block (e.g. from getInputs)
returns : integer, or ''
- Note : queryInputs and queryResponses are coordinately enumerated!
+ Note : Inputs and Responses are coordinately enumerated!
The integer you get here is what you
pass as the third argument to the simpleResponse or collectionResponse
subroutine to associate the numbered input to the numbered response</pre>
<p>
</p>
-<h2><a name="getarticles">getArticles</a></h2>
+<h2><a name="getarticlesasobjects">getArticlesAsObjects</a></h2>
<pre>
- name : getArticles
+ name : DO NOT USE!!
function : get the Simple/Collection articles for a single queryInput
- or queryResponse node
+ or queryResponse node, rethrning them as SimpleArticle,
+ SecondaryArticle, or ServiceInstance objects
usage : @articles = getArticles($XML)
- args : raw XML or XML::DOM of a moby:queryInput or a moby:queryResponse block
- returns : a list of listrefs; each listref is one component of the queryInput.
- a single queryInput/Responsemay consist of one or more named or unnamed
- simple or collection articles. The listref structure is thus [name, $ARTICLE]:
-
- e.g.: @articles = ['name1', $SIMPLE_DOM]
- or : @articles = ['name1', $COLLECTION_DOM], ['name2', $SIMPLE_DOM]...</pre>
-<pre>
- the former is generated from the following sample XML:</pre>
-<pre>
- <queryInput>
- <Simple articleName='name1'>
- <Object namespace=blah id=blah/>
- </Simple>
- </queryInput>
- <queryInput>
- <Simple articleName='name1'>
- <Object namespace=blah id=blah/>
- </Simple>
- </queryInput></pre>
+ args : raw XML or XML::DOM of a moby:queryInput, moby:queryResponse block
+ returns :</pre>
<p>
</p>
<h2><a name="getcollectedsimples">getCollectedSimples</a></h2>
@@ -346,18 +500,18 @@
the former is generated from the following XML:
...
- <moby:Query>
- <queryInput>
+ <moby:mobyContent>
+ <moby:mobyData>
<Simple>
<Object namespace=blah id=blah/>
</Simple>
- </queryInput>
- <queryInput>
+ </moby:mobyData>
+ <moby:mobyData>
<Simple>
<Object namespace=blah id=blah/>
</Simple>
- </queryInput>
- </moby:Query>
+ </moby:mobyData>
+ </moby:mobyContent>
...</pre>
<p>
</p>
@@ -379,6 +533,25 @@
returns : boolean</pre>
<p>
</p>
+<h2><a name="issecondaryarticle">isSecondaryArticle</a></h2>
+<pre>
+ name : isSecondaryArticle
+ function : tests XML (text) or an XML DOM node to see if it represents a Secondary article
+ usage : if (isSecondaryArticle($node)){do something to it}
+ input : an XML::DOM node, an XML::DOM::Document or straight XML
+ returns : boolean</pre>
+<p>
+</p>
+<h2><a name="extractrawcontent">extractRawContent</a></h2>
+<pre>
+ name : extractRawContent
+ function : pass me an article (Simple, or Collection) and I'll give you the
+ content AS A STRING - i.e. the raw XML of the contained MOBY Object(s)
+ usage : extractRawContent($simple)
+ input : the one element of the output from getArticles
+ returns : string</pre>
+<p>
+</p>
<h2><a name="getnodecontentwitharticle">getNodeContentWithArticle</a></h2>
<pre>
name : getNodeContentWithArticle
@@ -396,16 +569,16 @@
For example, in the following XML:
...
...
- <moby:Query>
- <queryInput>
+ <moby:mobyContent>
+ <moby:mobyData>
<Simple>
<Sequence namespace=blah id=blah>
<Integer namespace='' id='' articleName="Length">3</Integer>
<String namespace='' id='' articleName="SequenceString">ATG</String>
</Sequence>
</Simple>
- </queryInput>
- </moby:Query>
+ </moby:mobyData>
+ </moby:mobyContent>
...
...
@@ -422,16 +595,6 @@
}</pre>
<p>
</p>
-<h2><a name="extractrawcontent">extractRawContent</a></h2>
-<pre>
- name : extractRawContent
- function : pass me an article (Simple, or Collection) and I'll give you the
- content AS A STRING - i.e. the raw XML of the contained MOBY Object(s)
- usage : extractRawContent($simple)
- input : the one element of the output from getArticles
- returns : string</pre>
-<p>
-</p>
<h2><a name="validatenamespaces">validateNamespaces</a></h2>
<pre>
name : validateNamespaces
@@ -462,6 +625,15 @@
an array-ref of Simple article XML::DOM::Node's</pre>
<p>
</p>
+<h2><a name="getservicenotes">getServiceNotes</a></h2>
+<pre>
+ name : getServiceNotes
+ function : to get the content of the Service Notes block of the MOBY message
+ usage : getServiceNotes($message)
+ args : $message is either the XML::DOM of the MOBY message, or plain XML
+ returns : String content of the ServiceNotes block of the MOBY Message</pre>
+<p>
+</p>
<h2><a name="getcrossreferences">getCrossReferences</a></h2>
<pre>
name : getCrossReferences
@@ -496,8 +668,78 @@
args : $CENTRAL - your MOBY::Client::Central object
$queryTerm - the object type I am interested in
\@termlist - the list of object types that I know about
- returns : an ontology term as a scalar, or undef if there
- is no parent of this node in the nodelist</pre>
+ returns : an ontology term and LSID as a scalar, or undef if there
+ is no parent of this node in the nodelist.
+ (note that it will only return the term if you give it
+ term names in the @termList. If you give it
+ LSID's in the termList, then both the parameters
+ returned will be LSID's - it doesn't back-translate...)</pre>
+<p>
+</p>
+<h2><a name="_rearrange__stolen_from_bioperl_____">_rearrange (stolen from BioPerl ;-) )</a></h2>
+<pre>
+ Usage : $object->_rearrange( array_ref, list_of_arguments)
+ Purpose : Rearranges named parameters to requested order.
+ Example : $self->_rearrange([qw(SEQUENCE ID DESC)], at param);
+ : Where @param = (-sequence => $s,
+ : -desc => $d,
+ : -id => $i);
+ Returns : @params - an array of parameters in the requested order.
+ : The above example would return ($s, $i, $d).
+ : Unspecified parameters will return undef. For example, if
+ : @param = (-sequence => $s);
+ : the above _rearrange call would return ($s, undef, undef)
+ Argument : $order : a reference to an array which describes the desired
+ : order of the named parameters.
+ : @param : an array of parameters, either as a list (in
+ : which case the function simply returns the list),
+ : or as an associative array with hyphenated tags
+ : (in which case the function sorts the values
+ : according to @{$order} and returns that new array.)
+ : The tags can be upper, lower, or mixed case
+ : but they must start with a hyphen (at least the
+ : first one should be hyphenated.)
+ Source : This function was taken from CGI.pm, written by Dr. Lincoln
+ : Stein, and adapted for use in Bio::Seq by Richard Resnick and
+ : then adapted for use in Bio::Root::Object.pm by Steve Chervitz,
+ : then migrated into Bio::Root::RootI.pm by Ewan Birney.
+ Comments :
+ : Uppercase tags are the norm,
+ : (SAC)
+ : This method may not be appropriate for method calls that are
+ : within in an inner loop if efficiency is a concern.
+ :
+ : Parameters can be specified using any of these formats:
+ : @param = (-name=>'me', -color=>'blue');
+ : @param = (-NAME=>'me', -COLOR=>'blue');
+ : @param = (-Name=>'me', -Color=>'blue');
+ : @param = ('me', 'blue');
+ : A leading hyphenated argument is used by this function to
+ : indicate that named parameters are being used.
+ : Therefore, the ('me', 'blue') list will be returned as-is.
+ :
+ : Note that Perl will confuse unquoted, hyphenated tags as
+ : function calls if there is a function of the same name
+ : in the current namespace:
+ : -name => 'foo' is interpreted as -&name => 'foo'
+ :
+ : For ultimate safety, put single quotes around the tag:
+ : ('-name'=>'me', '-color' =>'blue');
+ : This can be a bit cumbersome and I find not as readable
+ : as using all uppercase, which is also fairly safe:
+ : (-NAME=>'me', -COLOR =>'blue');
+ :
+ : Personal note (SAC): I have found all uppercase tags to
+ : be more managable: it involves less single-quoting,
+ : the key names stand out better, and there are no method naming
+ : conflicts.
+ : The drawbacks are that it's not as easy to type as lowercase,
+ : and lots of uppercase can be hard to read.
+ :
+ : Regardless of the style, it greatly helps to line
+ : the parameters up vertically for long/complex lists.
+
+</pre>
</body>
===================================================================
RCS file: /home/repository/moby/moby-live/Perl/MOBY/CommonSubs.pm,v
retrieving revision 1.44
retrieving revision 1.45
diff -u -r1.44 -r1.45
--- /home/repository/moby/moby-live/Perl/MOBY/CommonSubs.pm 2004/04/14 19:56:59 1.44
+++ /home/repository/moby/moby-live/Perl/MOBY/CommonSubs.pm 2004/04/14 20:10:35 1.45
@@ -8,7 +8,9 @@
=cut
-=head1 Client Side Paradigm
+=head2 Client Side Paradigm
+
+not written yet
=cut
@@ -51,7 +53,7 @@
# now take the namespace and ID from our input article
# (see pod docs for other possibilities)
my $namespace = getSimpleArticleNamespaceURI($input); # get namespace
- my ($identifier) = getSimpleArticleIDs($input); # get ID (note array output! see pod)
+ my ($identifier) = getSimpleArticleIDs($input); # get ID (note array output! see pod)
# here is where you do whatever manipulation you need to do
# for your particular service.
@@ -70,9 +72,9 @@
This is a service that:
-CONSUMES: base Object in the GO namespace
-EXECUTES: Retrieval
-PRODUCES: GO_Term (in the GO namespace)
+ CONSUMES: base Object in the GO namespace
+ EXECUTES: Retrieval
+ PRODUCES: GO_Term (in the GO namespace)
# this subroutine is called from your dispatch_with line
@@ -101,28 +103,28 @@
$MOBY_RESPONSE .= simpleResponse("", "", $ID);
next;
} else {
- my $ns = getSimpleArticleNamespaceURI($input);
- (($MOBY_RESPONSE .= simpleResponse("", "", $ID)) && (next))
- unless validateThisNamespace($ns, @validNS); # only do this if you are truly validating namespaces
- my ($accession) = defined(getSimpleArticleIDs($ns, [$input]))?getSimpleArticleIDs($ns,[$input]):undef;
- unless (defined($accession)){
- $MOBY_RESPONSE .= simpleResponse("", "", $ID);
- next;
- }
- unless ($accession =~/^GO:/){
- $accession = "GO:$accession"; # we still haven't decided on whether id's should include the prefix...
- }
- $sth->execute($accession);
- my ($term, $def) = $sth->fetchrow_array;
- if ($term){
- $MOBY_RESPONSE .= simpleResponse("
- <moby:GO_Term namespace='GO' id='$accession'>
- <moby:String namespace='' id='' articleName='Term'>$term</moby:String>
- <moby:String namespace='' id='' articleName='Definition'>$def</moby:String>
- </moby:GO_Term>", "GO_Term_From_ID", $ID)
- } else {
- $MOBY_RESPONSE .= simpleResponse("", "", $ID)
- }
+ my $ns = getSimpleArticleNamespaceURI($input);
+ (($MOBY_RESPONSE .= simpleResponse("", "", $ID)) && (next))
+ unless validateThisNamespace($ns, @validNS); # only do this if you are truly validating namespaces
+ my ($accession) = defined(getSimpleArticleIDs($ns, [$input]))?getSimpleArticleIDs($ns,[$input]):undef;
+ unless (defined($accession)){
+ $MOBY_RESPONSE .= simpleResponse("", "", $ID);
+ next;
+ }
+ unless ($accession =~/^GO:/){
+ $accession = "GO:$accession"; # we still haven't decided on whether id's should include the prefix...
+ }
+ $sth->execute($accession);
+ my ($term, $def) = $sth->fetchrow_array;
+ if ($term){
+ $MOBY_RESPONSE .= simpleResponse("
+ <moby:GO_Term namespace='GO' id='$accession'>
+ <moby:String namespace='' id='' articleName='Term'>$term</moby:String>
+ <moby:String namespace='' id='' articleName='Definition'>$def</moby:String>
+ </moby:GO_Term>", "GO_Term_From_ID", $ID)
+ } else {
+ $MOBY_RESPONSE .= simpleResponse("", "", $ID)
+ }
}
}
@@ -857,45 +859,13 @@
=head2 getArticlesAsObjects
- name : getArticlesAsObjects
+ name : DO NOT USE!!
function : get the Simple/Collection articles for a single queryInput
or queryResponse node, rethrning them as SimpleArticle,
SecondaryArticle, or ServiceInstance objects
usage : @articles = getArticles($XML)
args : raw XML or XML::DOM of a moby:queryInput, moby:queryResponse block
- returns : a list of listrefs; each listref is one component of the queryInput.
- a single queryInput/Response may consist of one or more named or unnamed
- simple, collection, or parameter articles.
- The listref structure is thus [name, $ARTICLE_OBJECT]:
-
- e.g.: @articles = ['name1', $SimpleArticle]
-
- generated from the following sample XML:
-
- <queryInput>
- <Simple articleName='name1'>
- <Object namespace=blah id=blah/>
- </Simple>
- </queryInput>
-
- or : @articles = ['name1', $CollectionArticle], ['paramname1', $SecondaryArticle]
-
- generated from the following sample XML:
-
- <queryInput>
- <Collection articleName='name1'>
- <Simple>
- <Object namespace=blah id=blah/>
- </Simple>
- <Simple>
- <Object namespace=blah id=blah/>
- </Simple>
- </Collection>
- <Parameter articleName='e value cutoff'>
- <datatype>Float</datatype>
- <default>10</default>
- </Parameter>
- </queryInput>
+ returns :
=cut
@@ -1327,10 +1297,10 @@
=head2 getServiceNotes
name : getServiceNotes
- function :
- usage :
- args :
- returns :
+ function : to get the content of the Service Notes block of the MOBY message
+ usage : getServiceNotes($message)
+ args : $message is either the XML::DOM of the MOBY message, or plain XML
+ returns : String content of the ServiceNotes block of the MOBY Message
=cut
@@ -1518,7 +1488,7 @@
# _rearrange stolen from BioPerl's Bio::RootI.pm
# because it is just so useful!
-=head2 _rearrange
+=head2 _rearrange (stolen from BioPerl ;-) )
Usage : $object->_rearrange( array_ref, list_of_arguments)
Purpose : Rearranges named parameters to requested order.
More information about the MOBY-guts
mailing list