<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="generator" content="Docutils 0.2.8: http://docutils.sourceforge.net/" /> <title>Query Interface Definition</title> <meta name="author" content="vieglais" /> <meta name="date" content="2003-05-08" /> <link rel="stylesheet" href="default.css" type="text/css" /> </head> <body> <div class="document" id="query-interface-definition"> <h1 class="title">Query Interface Definition</h1> <table class="docinfo" frame="void" rules="none"> <col class="docinfo-name" /> <col class="docinfo-content" /> <tbody valign="top"> <tr><th class="docinfo-name">Author:</th> <td>vieglais</td></tr> <tr><th class="docinfo-name">Revision:</th> <td>1.3</td></tr> <tr><th class="docinfo-name">Date:</th> <td>2003-05-08</td></tr> </tbody> </table> <div class="contents topic" id="contents"> <p class="topic-title"><a name="contents">Contents</a></p> <ul class="simple"> <li><a class="reference" href="#overview" id="id5" name="id5">Overview</a><ul> <li><a class="reference" href="#status" id="id6" name="id6">Status</a></li> <li><a class="reference" href="#see-also" id="id7" name="id7">See Also</a></li> </ul> </li> <li><a class="reference" href="#operations" id="id8" name="id8">Operations</a><ul> <li><a class="reference" href="#search" id="id9" name="id9">search</a><ul> <li><a class="reference" href="#parameters" id="id10" name="id10">Parameters</a></li> <li><a class="reference" href="#return" id="id11" name="id11">Return</a></li> </ul> </li> <li><a class="reference" href="#inventory" id="id12" name="id12">inventory</a><ul> <li><a class="reference" href="#id1" id="id13" name="id13">Parameters</a></li> <li><a class="reference" href="#id2" id="id14" name="id14">Return</a></li> </ul> </li> <li><a class="reference" href="#update" id="id15" name="id15">update</a><ul> <li><a class="reference" href="#id3" id="id16" name="id16">Parameters</a></li> <li><a class="reference" href="#id4" id="id17" name="id17">Return</a></li> </ul> </li> <li><a class="reference" href="#about-this-document" id="id18" name="id18">About This Document</a></li> </ul> </li> </ul> </div> <div class="section" id="overview"> <h1><a class="toc-backref" href="#id5" name="overview">Overview</a></h1> <p>The Query Interface Definition is a WSDL document that defines the operations and data structures of the query operation of the EcoGRID.</p> <p><strong>Note:</strong> should this really be called "Data Access" instead of "Query"?</p> <div class="section" id="status"> <h2><a class="toc-backref" href="#id6" name="status">Status</a></h2> <p>The wsdl document has been moved to /seek/projects/ecogrid/src/xsd/QueryInterface.wsdl</p> <p>The interface specification should be considered a preliminary draft and open for comment.</p> </div> <div class="section" id="see-also"> <h2><a class="toc-backref" href="#id7" name="see-also">See Also</a></h2> <dl> <dt>QueryInterface.wsdl</dt> <dd><a class="reference" href="http://cvs.ecoinformatics.org/cvs/cvsweb.cgi/~checkout~/seek/projects/ecogrid/src/xsd/QueryInterface.wsdl?content-type=text/plain">http://cvs.ecoinformatics.org/cvs/cvsweb.cgi/~checkout~/seek/projects/ecogrid/src/xsd/QueryInterface.wsdl?content-type=text/plain</a></dd> <dt>query.xsd</dt> <dd><a class="reference" href="http://cvs.ecoinformatics.org/cvs/cvsweb.cgi/~checkout~/seek/projects/ecogrid/src/xsd/query.xsd?content-type=text/plain">http://cvs.ecoinformatics.org/cvs/cvsweb.cgi/~checkout~/seek/projects/ecogrid/src/xsd/query.xsd?content-type=text/plain</a> or a <a class="reference" href="query.htm">html rendering of query.xsd</a>.</dd> <dt>resultset.xsd</dt> <dd><a class="reference" href="http://cvs.ecoinformatics.org/cvs/cvsweb.cgi/~checkout~/seek/projects/ecogrid/src/xsd/resultset.xsd?content-type=text/plain">http://cvs.ecoinformatics.org/cvs/cvsweb.cgi/~checkout~/seek/projects/ecogrid/src/xsd/resultset.xsd?content-type=text/plain</a> or a <a class="reference" href="resultset.htm">html rendering of resultset.xsd</a>.</dd> <dt>Generic SOAP client built from WSDL</dt> <dd><a class="reference" href="http://www.soapclient.com/soapclient?template=%2Fclientform.html&fn=soapform&SoapTemplate=%2FSoapResult.html&SoapWSDL=http%3A%2F%2Fcvs.ecoinformatics.org%2Fcvs%2Fcvsweb.cgi%2F%7Echeckout%7E%2Fseek%2Fprojects%2Fecogrid%2Fsrc%2Fxsd%2FQueryInterface.wsdl%3Fcontent-type%3Dtext%2Fplain&_ArraySize=2&CacheWSDL=0">http://www.soapclient.com/soapclient?template=%2Fclientform.html&fn=soapform&SoapTemplate=%2FSoapResult.html&SoapWSDL=http%3A%2F%2Fcvs.ecoinformatics.org%2Fcvs%2Fcvsweb.cgi%2F%7Echeckout%7E%2Fseek%2Fprojects%2Fecogrid%2Fsrc%2Fxsd%2FQueryInterface.wsdl%3Fcontent-type%3Dtext%2Fplain&_ArraySize=2&CacheWSDL=0</a></dd> </dl> </div> </div> <div class="section" id="operations"> <h1><a class="toc-backref" href="#id8" name="operations">Operations</a></h1> <p>Three operations are defined in the ecogrid query interface:</p> <dl> <dt>search</dt> <dd>Returns a subset of content from a specified <tt class="literal"><span class="pre">resource</span></tt> by comparing records against a supplied filter.</dd> <dt>inventory</dt> <dd>Returns a list of unique values that occur within a data element (column, field) of a resource plus the number of occurrences of each value.</dd> <dt>update</dt> <dd>Mechanism to permit remote modification of content in a resource. Records may be modified, appended or delete with this operation.</dd> </dl> <p>Each operation contains a <tt class="literal"><span class="pre">clientInfo</span></tt> structure that is currently defined to contain a timestamp and a client identifier (e.g. IP address). This data structure is meant as a place holder for more sophisticated content that may for example be used for client authentication.</p> <div class="section" id="search"> <h2><a class="toc-backref" href="#id9" name="search">search</a></h2> <p>The search operation returns zero or more records from a resource that match a supplied filter.</p> <div class="section" id="parameters"> <h3><a class="toc-backref" href="#id10" name="parameters">Parameters</a></h3> <dl> <dt><tt class="literal"><span class="pre">clientInfo</span></tt></dt> <dd>See discussion about clientInfo in the <a class="reference" href="#operations">Operations</a> section introduction.</dd> <dt><tt class="literal"><span class="pre">resource</span></tt></dt> <dd>The name of the resource (database) against which the operation is being performed. A single instance of a service supporting the eco-grid query interface may expose more than a single resource.</dd> <dt><tt class="literal"><span class="pre">filter</span></tt></dt> <dd>A filter structure that defines the subset of records that will be returned in a search response.</dd> <dt><tt class="literal"><span class="pre">startRecord</span></tt></dt> <dd>A positive integer that specifies the zero based index of the first record to retrieve from the set of records that match the filter.</dd> <dt><tt class="literal"><span class="pre">numRecords</span></tt></dt> <dd>A positive integer that specifies the number of records to be returned from the set of records that match the filter.</dd> <dt><tt class="literal"><span class="pre">matchCount</span></tt></dt> <dd>A boolean value that indicates if the number of matching records should be available in the response. If false, then the number of matching records may not ne returned in the response (i.e. the value of <tt class="literal"><span class="pre">matchCount</span></tt> in the response is not reliable).</dd> </dl> </div> <div class="section" id="return"> <h3><a class="toc-backref" href="#id11" name="return">Return</a></h3> <p>A <tt class="literal"><span class="pre">SearchResponse</span></tt> message is generated in response to a <tt class="literal"><span class="pre">SearchRequest</span></tt> operation. The <tt class="literal"><span class="pre">SearchResponse</span></tt> message contains a <tt class="literal"><span class="pre">clientInfo</span></tt> structure, the number of records that match the filter (value not reliable unless <tt class="literal"><span class="pre">matchCount</span></tt> is TRUE in the <tt class="literal"><span class="pre">SearchRequest</span></tt>), a boolean flag indicating if more records are available than were returned, and a <tt class="literal"><span class="pre">resultset</span></tt> structure that contains an array or records as well as a metadata section that describes the resultset.</p> </div> </div> <div class="section" id="inventory"> <h2><a class="toc-backref" href="#id12" name="inventory">inventory</a></h2> <p>The inventory operation may be considered equivalent to the SQL operation:</p> <pre class="literal-block"> SELECT fld, count() AS fldCnt FROM aTable GROUP BY fld ORDER BY fld ASC </pre> <div class="section" id="id1"> <h3><a class="toc-backref" href="#id13" name="id1">Parameters</a></h3> <dl> <dt><tt class="literal"><span class="pre">clientInfo</span></tt></dt> <dd>See discussion about clientInfo in the <a class="reference" href="#operations">Operations</a> section introduction.</dd> <dt><tt class="literal"><span class="pre">resource</span></tt></dt> <dd>The name of the resource (database) against which the operation is being performed. A single instance of a service supporting the eco-grid query interface may expose more than a single resource.</dd> <dt><tt class="literal"><span class="pre">elementName</span></tt></dt> <dd>Identifier of the element the operation is being performed on. (<strong>Note:</strong> change this to <tt class="literal"><span class="pre">elementPath</span></tt> to specify a path within a structure, as in XPath within an XML document).</dd> <dt><tt class="literal"><span class="pre">filter</span></tt></dt> <dd>An optional filter that specifies the subset of records on which the inventory operation is to be performed.</dd> </dl> </div> <div class="section" id="id2"> <h3><a class="toc-backref" href="#id14" name="id2">Return</a></h3> <p>An <tt class="literal"><span class="pre">InventoryResponse</span></tt> message is generated in response to an <tt class="literal"><span class="pre">InventoryRequest</span></tt> message. The <tt class="literal"><span class="pre">InventoryResponse</span></tt> contains a <tt class="literal"><span class="pre">clientInfo</span></tt> section, a recordSet and a boolean flag indicating if the response contains the complete resultset or if the response was truncated (an ecogrid query service may decide to limit the amount of information available in a single request).</p> <p>The recordSet contains simple records that contain the value of a field and the number of occurrences of that value within that field.</p> </div> </div> <div class="section" id="update"> <h2><a class="toc-backref" href="#id15" name="update">update</a></h2> <p>The update operation permits editing, deleting and appending records in a resource. Records that are to be updated are included in the request message. There must be sufficient information in each record to uniquely identify the intended target record within the resource (e.g. using a row ID).</p> <div class="section" id="id3"> <h3><a class="toc-backref" href="#id16" name="id3">Parameters</a></h3> <dl> <dt><tt class="literal"><span class="pre">clientInfo</span></tt></dt> <dd>See discussion about clientInfo in the <a class="reference" href="#operations">Operations</a> section introduction.</dd> <dt><tt class="literal"><span class="pre">resource</span></tt></dt> <dd>The name of the resource (database) against which the operation is being performed. A single instance of a service supporting the eco-grid query interface may expose more than a single resource.</dd> <dt><tt class="literal"><span class="pre">updateMethod</span></tt></dt> <dd>An enumerated type that can be one of <tt class="literal"><span class="pre">update</span></tt>, <tt class="literal"><span class="pre">append</span></tt> or <tt class="literal"><span class="pre">delete</span></tt>.</dd> <dt><tt class="literal"><span class="pre">records</span></tt></dt> <dd>The set of records that are to be updated, appended, or deleted. When records are being deleted, only a unique identifier is required to indicate which records are being deleted, otherwise each record should contain the complete content.</dd> </dl> </div> <div class="section" id="id4"> <h3><a class="toc-backref" href="#id17" name="id4">Return</a></h3> <p>An <tt class="literal"><span class="pre">UpdateResponse</span></tt> message is generated in reponse to an <tt class="literal"><span class="pre">UpdateRequest</span></tt> message. The <tt class="literal"><span class="pre">UpdateResponse</span></tt> contains a <tt class="literal"><span class="pre">clientInfo</span></tt> section and an array of status records indicating the success or otherwise of the update operation for each record in the request.</p> </div> </div> <div class="section" id="about-this-document"> <h2><a class="toc-backref" href="#id18" name="about-this-document">About This Document</a></h2> <blockquote> This document is formatted as reStructuredText (<a class="reference" href="http://docutils.sourceforge.net/rst.html">http://docutils.sourceforge.net/rst.html</a>) which can be processed to html, docbook, pdf, or TeX with various docUtils (<a class="reference" href="http://docutils.sourceforge.net">http://docutils.sourceforge.net</a>) tools.</blockquote> </div> </div> </div> </body> </html>