source: TI01-discovery/trunk/ws-Discovery2/docs/overview.html @ 3076

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI01-discovery/trunk/ws-Discovery2/docs/overview.html@3076
Revision 3076, 29.4 KB checked in by mpritcha, 13 years ago (diff)

Initial stab at documentation, exists as extension to javadocs.

Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<HTML>
3<HEAD>
4<TITLE>NDG Discovery Web Service</TITLE>
5<!--
6
7  $Id: overview.html
8
9-->
10</HEAD>
11
12<BODY bgColor=white>
13
14<h1>NDG Discovery Web Service</h1>
15<address>
16Matt Pritchard
17</address>
18<h2>Introduction</h2>
19<p>This document describes the NDG discovery web service and the behaviour of its operations. The service consists of the following components:</p>
20<ul>
21  <li>Code package, consisting of:
22    <ul>
23      <li>WSDL document [<a href="http://proj.badc.rl.ac.uk/ndg/browser/TI01-discovery/trunk/ws-Discovery2/wsdl/Discovery.wsdl" title="DiscoveryService.wsdl">DiscoveryService.wsdl</a> (in SVN repository)]
24        <ul>
25          <li>Defines the interface presented by the web service by specifying the operations and their component message structures.</li>
26        </ul>
27      </li>
28      <li>Server code [<a href="http://proj.badc.rl.ac.uk/ndg/browser/TI01-discovery/trunk/ws-Discovery2">ws-Discovery2</a> (SVN)]
29        <ul>
30          <li>Generated in skeleton form from the WSDL, then extended with business logic such as database interaction etc).</li>
31        </ul>
32      </li>
33      <li>Client code [<a href="http://proj.badc.rl.ac.uk/ndg/browser/TI01-discovery/trunk/ws-Discovery2">ws-Discovery2</a> (SVN)]
34        <ul>
35          <li>Generated in stub form from the WSDL, then extended to provide an example of a simple client interface.</li>
36        </ul>
37      </li>
38    </ul>
39  </li>
40  <li>Service deployment
41    <ul>
42      <li>Currently at <a href="http://glue.badc.rl.ac.uk/axis2/services/DiscoveryService">http://glue.badc.rl.ac.uk/axis2/services/DiscoveryService</a>
43        <ul>
44          <li><a href="http://glue.badc.rl.ac.uk/axis2/services/DiscoveryService?wsdl" title="DiscoveryService.wsdl">DiscoveryService.wsdl</a> (live)</li>
45        </ul>
46      </li>
47    </ul>
48  </li>
49</ul>
50<h2>Quick start</h2>
51<p>To interact with the service via a generic SOAP client such as XMLSpy or OxygenXML, point the client at the WSDL exposed by the deployed service, <a href="http://glue.badc.rl.ac.uk/axis2/services/DiscoveryService?wsdl">http://glue.badc.rl.ac.uk/axis2/services/DiscoveryService?wsdl</a>.</p>
52<p>In XMLSpy, the following sequence demonstrates a simple full-text search using the service:</p>
53<ol>
54  <li>From the SOAP Menu, click &quot;Create new SOAP request&quot;, enter the WSDL URI and click OK.</li>
55  <li>Select one of the listed ports to connect to, for example, <code>DiscoveryService_DiscoveryServiceSOAP11port_http</code>, and click OK</li>
56  <li>Select the doSearch operation, listed as <code>doSearch( doSearch part1 )</code></li>
57  <li>A doSearchRequest document is shown. Modify if so that it looks like this: </li>
58</ol>
59<pre>&lt;SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"&gt;
60        &lt;SOAP-ENV:Body>
61                &lt;m:doSearch xmlns:m="urn:DiscoveryServiceAPI"&gt;
62                        &lt;m:term&gt;water&lt;/m:term&gt;
63                        &lt;m:termType&gt;fullText&lt;/m:termType&gt;
64                        &lt;/m:DateRange&gt;
65                &lt;/m:doSearch&gt;
66        &lt;/SOAP-ENV:Body&gt;
67&lt;/SOAP-ENV:Envelope&gt;
68  </pre>
69<ol start="5">
70  <li>From the SOAP menu, select &quot;Send request to server&quot;. A response message should be displayed, which looks like this: </li>
71</ol>
72<pre>
73&lt;?xml version="1.0" encoding="UTF-8"?&gt;
74&lt;soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"&gt;
75        &lt;soapenv:Header/&gt;
76        &lt;soapenv:Body&gt;
77                &lt;doSearchReturn xmlns="urn:DiscoveryServiceAPI"&gt;
78                        &lt;status&gt;true&lt;/status&gt;
79                        &lt;statusMessage&gt;Success&lt;/statusMessage&gt;
80                        &lt;resultId&gt;0&lt;/resultId&gt;
81                        &lt;hits&gt;413&lt;/hits&gt;
82                        &lt;documents&gt;
83                                &lt;document&gt;ndg.noc.soton.ac.uk__DIF__NOCSDAT3058.xml&lt;/document&gt;
84                                &lt;document&gt;ndg.noc.soton.ac.uk__DIF__NOCSDAT3059.xml&lt;/document&gt;
85                                &lt;document&gt;ndg.noc.soton.ac.uk__DIF__NOCSDAT3060.xml&lt;/document&gt;
86                                &lt;document&gt;ndg.noc.soton.ac.uk__DIF__NOCSDAT3061.xml&lt;/document&gt;
87                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480064.xml&lt;/document&gt;
88                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480070.xml&lt;/document&gt;
89                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480088.xml&lt;/document&gt;
90                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480138.xml&lt;/document&gt;
91                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480139.xml&lt;/document&gt;
92                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480140.xml&lt;/document&gt;
93                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480190.xml&lt;/document&gt;
94                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480203.xml&lt;/document&gt;
95                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480208.xml&lt;/document&gt;
96                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480219.xml&lt;/document&gt;
97                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480221.xml&lt;/document&gt;
98                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480222.xml&lt;/document&gt;
99                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480322.xml&lt;/document&gt;
100                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480341.xml&lt;/document&gt;
101                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480357.xml&lt;/document&gt;
102                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480374.xml&lt;/document&gt;
103                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480393.xml&lt;/document&gt;
104                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480395.xml&lt;/document&gt;
105                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480396.xml&lt;/document&gt;
106                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480405.xml&lt;/document&gt;
107                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480407.xml&lt;/document&gt;
108                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480411.xml&lt;/document&gt;
109                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480412.xml&lt;/document&gt;
110                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480441.xml&lt;/document&gt;
111                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13480485.xml&lt;/document&gt;
112                                &lt;document&gt;bgs.nerc.ac.uk__DIF__13602973.xml&lt;/document&gt;
113                        &lt;/documents&gt;
114                &lt;/doSearchReturn&gt;
115        &lt;/soapenv:Body&gt;
116&lt;/soapenv:Envelope&gt;
117</pre>
118<p>This shows a successful search, finding 413 hits for the term "water". By default, only the first 30 results are listed along with the total number of hits (413), but this behaviour can be changed by using the optional <code>&lt;start&gt;</code> and <code>&lt;howMany&gt;</code> elements of the doSearchRequest document. The results returned consist of the names of documents which can then be retrieved using the <code>doPresent</code> operation.</p>
119
120<h2>Installation</h2>
121
122
123
124<h3>Prerequisites (for both client and server installations) </h3>
125<p>The following packages are assumed to be installed already. If not, please follow the installation guidelines for each before proceding. Version numbers indicate those used for compilation at time of writing this documentation) </p>
126<ul>
127  <li>Sun Java Development Kit, Standard Edition (J2SE) v1.5.08 ( <a href="http://java.sun.com">http://java.sun.com</a>) </li>
128  <li>Apache Ant v1.6.5 (<a href="http://ant.apache.org">http://ant.apache.org</a>) </li>
129  <li>Apache Axis2 v1.1 (<a href="http://ws.apache.org/axis2">http://ws.apache.org/axis2</a>) </li>
130  <li>JDOM v1.1 (<a href="http://www.jdom.org">http://www.jdom.org</a>)   </li>
131</ul>
132<h3>Procedure</h3>
133<p>Check out the <a href="http://proj.badc.rl.ac.uk/ndg/browser/TI01-discovery/trunk/ws-Discovery2">code</a> from the SVN repository. The base directory, ws-Discovery2 should contain two source directories, <code>src</code> and <code>srcgen</code>.</p>
134<p>The file <code>readme.txt</code>, in the base directory of the distribution, gives instructions on how to automatically generate client stub and service skeleton code from the WSDL, and how to compile this using the ant build script, <code>buildDiscovery.xml</code>, to be run from within directory <code>srcgen</code>. This build script sets up the Java classpath and provides the compilation procedure and also the facility to generate Javadoc documentation and run the client code.</p>
135<h2>Service operations</h2>
136<p>The WSDL document describes the operations provided by the service, providing the information necessary for a client to connect to and exchange SOAP messages with each of the operations:</p>
137<ul>
138  <li>getListNames</li>
139  <li>getList</li>
140  <li>doSearch</li>
141  <li>doPresent</li>
142</ul>
143<p>The behavious of each of these operations will be described in detail here.</p>
144<h3>getListNames</h3>
145<p>The service relies on several lists of valid terms which are specific to the functionality of this service. The reason for using these 2 &quot;helper&quot; operations rather than encoding these valid terms as  <code>&lt;xs:enumeration&gt;</code> in the schema part of the WSDL, is so that future modifications to the service need not necessarily require the modification of the WSDL (which can be incovenient for clients already developed around a particular release of the WSDL). The <code>getListNames</code> operation simply returns the names of these lists, which can then be used in a subsequent call to the <code>getList</code> operation.</p>
146<p>The WSDL document defines the <code>getListNamesRequest</code> message as an empty <code>&lt;getListNames&gt;</code> element, so the request message should look like this (omitting the SOAP Envelope &amp; Body parent elements from now on):</p>
147<pre>&lt;m:getListNames xmlns:m="urn:DiscoveryServiceAPI"/&gt;</pre>
148<p>The <code>getListNamesResponse</code> message comprises a <code>&lt;getListNamesReturn&gt;</code> element, with child elements containing the names of the lists available for inspection:</p>
149<pre>
150&lt;getListNamesReturn xmlns="urn:DiscoveryServiceAPI"&gt;
151        &lt;listNames&gt;
152                &lt;listName&gt;presentFormatList&lt;/listName&gt;
153                &lt;listName&gt;orderByFieldList&lt;/listName&gt;
154                &lt;listName&gt;scopeList&lt;/listName&gt;
155                &lt;listName&gt;termTypeList&lt;/listName&gt;
156                &lt;listName&gt;spatialOperatorList&lt;/listName&gt;
157        &lt;/listNames&gt;
158&lt;/getListNamesReturn&gt;
159</pre>
160<h3>getList</h3>
161<p>The contents of each of the lists named by the <code>getListNames</code> operation are accessible by invoking a call to the <code>getList</code> operation, with the name of the list as the single argument, encoded as a <code>getListRequest</code> message, as defined in the WSDL. :</p>
162<pre>
163&lt;getListReturn xmlns="urn:DiscoveryServiceAPI"&gt;
164        &lt;list name="presentFormatList"&gt;
165                &lt;listMember&gt;original&lt;/listMember&gt;
166                &lt;listMember&gt;DC&lt;/listMember&gt;
167                &lt;listMember&gt;DIF&lt;/listMember&gt;
168                &lt;listMember&gt;MDIP&lt;/listMember&gt;
169                &lt;listMember&gt;ISO19115&lt;/listMember&gt;
170        &lt;/list&gt;
171&lt;/getListReturn&gt;
172</pre>
173<p>An explanation of the <code>presentFormatList</code> list is given later, in the context of the <code>doPresent</code> operation.
174<h3>doSearch</h3>
175<p>The <code>doSearch</code> operation provides an interface to search the NDG discovery database (a separate component, comprised of an XML database and spatio/temporal records in a relational database). Queries to this database are formulated from the <code>doSearchRequest</code> message, and are executed using XML-RPC and/or JDBC calls to these databases, hidden from the user of this service.</p>
176<p>Although outside the scope of the Discovery Web Service itself, it is worth explaining the structure of the NDG Discovery database which is searched by the service. Fig X shows the structure of the NDG discovery database, which is populated from records harvested via OAI from the NDG data providers. Records are currently harvested in GCMD DIF format, and are tagged at ingest time with one or more &quot;scope&quot; keywords (listed in the <code>scopeList</code> list available from the getList operation). These enable the search to be restricted to particular subgroups of the NDG community, namely NERC, NERC_DDC (Designated Data Centres) and MDIP (Marine Data Information Partnership). Limited quality control on ingested records is also applied at ingest time, and it is the responsibility of the data provider to ensure that metadata records are provided to sufficient quality to enable them to be visible in the system. Further instructions for data providers is available at XX.</p>
177<p>The doSearchRequest message is shown in schema form in fig X. </p>
178<p><img src="resources/doSearchSchema.png" alt="doSearchRequest message schema" width="467" height="639"></p>
179<h4>Choice of search type: <code>&lt;term&gt;</code> and <code>&lt;termType&gt;</code> </h4>
180<p>The only mandatory elements are <code>&lt;term&gt;</code> and <code>&lt;termType&gt;</code>, as used in the example &quot;Quick Start&quot;, above. By specifying the <code>&lt;termType&gt;</code>, a choice is made as to which of 3 variants of a full-text search should be invoked. This element should be populated with a valid value from the <code>termTypeList</code> list accessible via the <code>getList</code> operation. At present, these are: </p>
181<ul>
182  <li>fullText
183    <ul>
184      <li>A full-text search is applied to the whole discovery metadata record </li>
185    </ul>
186  </li>
187  <li>author
188    <ul>
189      <li>A full-text search is applied only to those sections of the discovery metadata record relating to authorship of the dataset</li>
190    </ul>
191  </li>
192  <li>parameter
193    <ul>
194      <li>A full-text search is applied only to the parameter listing section of the discovery metadata record</li>
195    </ul>
196  </li>
197</ul>
198<p>&lt;term&gt; should be populated with the search term, which can be a string of one or more words and wildcard characters. The service is currently configured to execute searches by attempting to match a node set from the target collection of XML documents (in the discovery database) to the term, where ALL of the components of the search term are matched (as opposed to ANY). In this way, increasingly specific searches can be used to refine the search results. Searches are case-insensitive. Examples of fullText search terms are: </p>
199<ul>
200  <li>temperature
201    <ul>
202      <li>Matches records with the word &quot;temperature&quot; in any node of a document</li>
203    </ul>
204  </li>
205  <li>sea surface temperature
206    <ul>
207      <li>Matches nodes (i.e. parts of a document) having the words &quot;sea&quot;, &quot;surface&quot; AND &quot;temperature&quot; (in any order)</li>
208    </ul>
209  </li>
210  <li>*neodc*
211    <ul>
212      <li>Matches nodes where the string &quot;neodc&quot; appears in any node, even if embedded within a larger string. </li>
213    </ul>
214  </li>
215</ul>
216<h4>Paging : <code>&lt;start&gt; </code>and <code>&lt;howMany&gt;</code> </h4>
217<p>The optional elements <code>&lt;start&gt;</code> and <code>&lt;howMany&gt;</code> control which records from the result set should be returned (although the total number of hits is always returned as a number to aid with paging in clients). If <code>&lt;start&gt;</code> is omitted, the default value used is 1 (i.e. the first record). If <code>&lt;howMany&gt;</code> is omitted, the default number of records returned is 30.</p>
218<h4>Ordering: <code>&lt;orderBy&gt;</code> and <code>&lt;orderByDirection&gt;</code></h4>
219<p>Ordering of the result set can be requested by setting &lt;orderBy&gt; to one of the valid values listed in the <code>orderByFieldList</code> accesible via the <code>getList</code> operation. Currently these are:</p>
220<ul>
221  <li>date
222    <ul>
223      <li>Specifically, the start date of the date range given for the temporal coverage of the metadata record </li>
224    </ul>
225  </li>
226  <li>dataCentre
227    <ul>
228      <li>Currently, the repository identifier of the curator of the described entity</li>
229    </ul>
230  </li>
231</ul>
232<p>In addition, the direction of ordering (ascending or descending) can be specified. If omitted, the default direction is descending. <em>Note: an error in the WSDL currently specifies &quot;<code>descnding</code>&quot; instead of &quot;<code>descending</code>&quot;.</em></p>
233<h4>Scope of search: <code>&lt;scope&gt;</code> </h4>
234<p>The optional <code>&lt;scope&gt;</code> element can be used to restrict the search to onr or more of the supported NDG Data Provider Groups, defined  in NDG controlled vocabulary http://vocab.ndg.nerc.ac.uk/list/N010/0. Currently supported values from this vocabulary are these are given in the the <code>scopeList</code> list accessible via the <code>getList</code> operation. Currently these are:</p>
235<ul>
236  <li>MDIP
237    <ul>
238      <li>Marine Data Information Partnership</li>
239    </ul>
240  </li>
241  <li>NERC_DDC
242    <ul>
243      <li>NERC Designated Data Centres</li>
244    </ul>
245  </li>
246  <li>NERC
247    <ul>
248      <li>NERC (General)  </li>
249    </ul>
250  </li>
251</ul>
252<p>If &lt;scope&gt; is omitted, the search is not restricted in this way.</p>
253<h4>Spatial searching : <code>&lt;spatialOperator&gt;</code> and <code>&lt;boundingBox&gt;</code></h4>
254<p>Full-text, author or parameter searches, as described above, may optionally be combined with a further restriction that the spatial coverage described in the metadata records match, according to the specified <code>&lt;spatialOperator&gt;</code>, the specified spatial <code>&lt;boundingBox&gt;</code>. <code>&lt;spatialOperator&gt;</code> may be populated with any of the values from the <code>spatialOperatorList</code> accessible via the <code>getList</code> operation. Currently, supported values are:</p>
255<ul>
256  <li>overlaps (default) </li>
257  <li>doesNotOverlap</li>
258  <li>within</li>
259</ul>
260<p>If <code>&lt;spatialOperator&gt;</code> is omitted, but a valid <code>&lt;boundingBox&gt;</code> is supplied, the default operator applied is <code>overlaps</code>. Values for <code>&lt;limitNorth&gt;</code>, <code>&lt;limitSouth&gt;</code>, <code>&lt;limitEast&gt;</code> and <code>&lt;limitWest&gt;</code> should be given in decimal degrees latitude and longitude. <code>&lt;limitNorth&gt;</code> and <code>&lt;limitSouth&gt;</code> must be in the range -90.0 to +90.0, with <code>&lt;limitNorth&gt;</code> greater than <code>&lt;limitSouth&gt;</code>. <code>&lt;limitWest&gt;</code> and <code>&lt;limitEast&gt;</code> must be in the range -180.0 to 180.0 and <code>&lt;limitEast&gt;</code> should be greater than <code>&lt;limitWest&gt;</code>. Bounding boxes that span the -180 degree meridian, or the poles, are not currently supported.</p>
261<p>Spatial searches (as a further restriction of &quot;term&quot; searches) are currently implemented by obtaining a resultset from the term search, obtaining a result set from the spatial search, then returning the intersection of the two result sets.</p>
262<h4>Temporal searching :<code> &lt;DateRange&gt;</code></h4>
263<p>Full-text, author or parameter searches my optionally be combined with a further restriction that the temporal coverage ovelaps  the specified <code>&lt;DateRange&gt;</code>. Both &lt;DateRangeStart&gt; and &lt;DateRangeEnd&gt; must be specified and must be valid dates of the form YYYY-MM-DD. <em>TODO: it is planned to implement a choice of <code>&lt;temporalOperator&gt;</code> in a similar manner to <code>&lt;spatialOperator&gt;</code>.</em></p>
264<h4>Search results</h4>
265<p>The <code>doSearchResponse</code> message is defined in the WSDL as shown below:</p>
266<p><img src="resources/doSearchReturnSchema.png" alt="doSearchResponse message schema" width="468" height="265"></p>
267<p>The <code>&lt;doSearchReturn&gt;</code> element  contains the following top-level elements:</p>
268<ul>
269  <li>status
270    <ul>
271      <li>true if successful AND number of hits &gt; 0, false otherwise (designed so that a client need only proceed to parse the rest of the message if results were successfully returned) </li>
272    </ul>
273  </li>
274  <li>statusMessage
275    <ul>
276      <li>Textual information regarding success / failure / errors</li>
277    </ul>
278  </li>
279  <li>resultId
280    <ul>
281      <li>reserved for future use </li>
282    </ul>
283  </li>
284  <li>hits
285    <ul>
286      <li>TOTAL number of hits returned</li>
287    </ul>
288  </li>
289  <li>documents
290    <ul>
291      <li>parent element for array of &lt;document&gt; elements containing returned document IDs</li>
292    </ul>
293  </li>
294</ul>
295<p>A typical search result was shown in the "Quick Start" section. A result where no hits were returned is shown below</p>
296<pre>
297&lt;doSearchReturn xmlns="urn:DiscoveryServiceAPI"&gt;
298        &lt;status&gt;false&lt;/status&gt;
299        &lt;statusMessage&gt;Search was successful but generated no results.&lt;/statusMessage&gt;
300        &lt;resultId&gt;0&lt;/resultId&gt;
301        &lt;hits&gt;0&lt;/hits&gt;
302&lt;/doSearchReturn&gt;
303</pre>
304<h3>doPresent</h3>
305<p>The <code>doPresent</code> operation provides a means of retrieving one or more XML documents from the database. The <code>doPresentRequest</code> message is defined as follows:</p>
306<p><img src="resources/doPresentSchema.png" alt="doPresentRequest message schema" width="438" height="166"> </p>
307<p>One or more &lt;document&gt; elements should each contain the names of a document (in the form returned in the <code>doSearchReturn</code> message) to be retreieved. The optional <code>&lt;format&gt;</code> element should be populated with one of the supported format names as listed by the <code>presentFormatList</code> accessible via the <code>getList</code> operation. All documents are returned in the same format from a given <code>doPresent</code> request. Currently-supported formats are:</p>
308<ul>
309  <li><code>original</code>
310    <ul>
311      <li>Documents are returned unaltered, in the format in which they were harvested (via OAI) from the data provider</li>
312    </ul>
313  </li>
314  <li><code>DC</code>
315    <ul>
316      <li>Dublin Core format</li>
317    </ul>
318  </li>
319  <li><code>DIF</code>
320    <ul>
321      <li>GCMD DIF format</li>
322    </ul>
323  </li>
324  <li><code>MDIP</code>
325    <ul>
326      <li>Metadata format used by the Marine Data and Information Partnership</li>
327    </ul>
328  </li>
329  <li><code>ISO19115</code>
330    <ul>
331      <li>ISO19115 (Geographic Information: Metadata) encoded as ISO19139 XML</li>
332    </ul>
333  </li>
334</ul>
335<p>For all formats except <code>original</code>, the following action is taken prior to returning the document:</p>
336<ul>
337  <li>Check if the document exists in the discovery database in the requested format, and if so, return it unaltered </li>
338  <li>Apply a conversion XQuery to create a new document in that format on-the-fly</li>
339</ul>
340<h4>doPresent response</h4>
341<p>The <code>doPresentResponse</code> message is defined in the WSDL as follows:</p>
342<p><img src="resources/doPresentReturnSchema.png" alt="doPresentReturn message schema" width="475" height="201"> </p>
343<p>The <code>&lt;doPresentReturn&gt;</code> element contains the following top-level elements:</p>
344<ul>
345  <li><code>&lt;status&gt;</code>
346    <ul>
347      <li>true if there are <em>any</em> documents returned in the payload, false otherwise.</li>
348    </ul>
349  </li>
350  <li><code>&lt;statusMessage&gt;</code></li>
351  <ul>
352    <li>Textual information regarding success / failure / errors.</li>
353  </ul>
354  <li><code>&lt;documents&gt;</code></li>
355  <ul>
356    <li>If <em>some</em> documents have been successfully returned, a <code>&lt;documents&gt;</code> element is present and will contain a child <code>&lt;document&gt;</code> element for each document retrieved. In the case where some but not all documents are successfully returned, the <code>&lt;documents&gt;</code> element will contain populated <code>&lt;document&gt;</code> elements for the successfully-retrieved documents, but an empty <code>&lt;document&gt;</code> element for those where retrieval failed. If NO documents are successfully returned, however, then the <code>&lt;status&gt;</code> is set to false and no <code>&lt;documents&gt;</code> element is included in the <code>doPresentResponse</code> message.</li>
357  </ul>
358</ul>
359<p>The &lt;document&gt; element, if present and populated, contains the retrieved document as an encapsulated string representation of the XMLDepending on the client used to display the payload document, it either appears contained within a &lt;![CDATA[ ... ]]&gt; construct, or as XML with the opening angle brackets &quot;&lt;&quot; escaped as &quot;&lt;&quot;. Most XML parsers should successfully parse the string to reconstruct the XML document, but it is returned in this form to avoid namespace issues. </p>
360<p>The following request / response sequence shows a successful doPresent operation:</p>
361<p>Request:</p>
362<pre>&lt;m:doPresent xmlns:m=&quot;urn:DiscoveryServiceAPI&quot;&gt;<br>        &lt;m:documents&gt;<br>         &lt;m:document&gt;badc.nerc.ac.uk__DIF__dataent_claus.xml&lt;/m:document&gt;<br>                &lt;m:document&gt;ndg.noc.soton.ac.uk__DIF__NOCSDAT160.xml&lt;/m:document&gt;<br>               &lt;m:document&gt;ndg.noc.soton.ac.uk__DIF__NOCSDAT162.xml&lt;/m:document&gt;<br>               &lt;m:document&gt;ndg.noc.soton.ac.uk__DIF__NOCSDAT163.xml&lt;/m:document&gt;<br>       &lt;/m:documents&gt;<br>        &lt;m:format&gt;original&lt;/m:format&gt;<br>&lt;/m:doPresent&gt;<br></pre>
363<p>Response:</p>
364<pre>&lt;doPresentReturn xmlns=&quot;urn:DiscoveryServiceAPI&quot;&gt;<br>      &lt;status&gt;true&lt;/status&gt;<br>   &lt;statusMessage&gt;Success&lt;/statusMessage&gt;<br>  &lt;documents&gt;<br>           &lt;document&gt;&amp;lt;DIF xmlns=&quot;http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/&quot; xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;&gt;&amp;lt;Entry_ID&gt;badc.nerc.ac.uk:DIF:dataent_claus&amp;lt;/Entry_ID&gt;&nbsp;(...)&nbsp;&amp;lt;/DIF&gt;&lt;/document&gt;<br>            &lt;document&gt;&amp;lt;DIF xmlns=&quot;http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/&quot; xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;&gt;&amp;lt;Entry_ID&gt;ndg.noc.soton.ac.uk__DIF__NOCSDAT160&amp;lt;/Entry_ID&gt;&nbsp;(...)&nbsp;&amp;lt;/DIF&gt;&lt;/document&gt;<br>         &lt;document&gt;&amp;&lt;DIF xmlns=&quot;http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/&quot; xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;&gt;&amp;lt;Entry_ID&gt;ndg.noc.soton.ac.uk__DIF__NOCSDAT162&amp;lt;/Entry_ID&gt;&nbsp;(...)&nbsp;&amp;lt;/DIF&gt;&lt;/document&gt;<br>                &lt;document&gt;&amp;lt;DIF xmlns=&quot;http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/&quot; xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;&gt;&amp;lt;Entry_ID&gt;ndg.noc.soton.ac.uk__DIF__NOCSDAT163&amp;lt;/EntryID&gt;&nbsp;(...)&nbsp;&amp;lt;/DIF&gt;&lt;/document&gt;<br>  &lt;/documents&gt;<br>&lt;/doPresentReturn&gt;<br>
365</pre>
366<h2>Helper package <a href="discoveryserviceapi/package-summary.html">discoveryserviceapi</a></h2>
367<p>This package, distinct from that of the service itself (<a href="ndg/services/discovery/package-summary.html">ndg.services.discovery</a>) is an automatically-generated set of helper classes, produced from the WSDL using the Axis2 tool WSDL2Java. These object classes represent the elements present in the various messages defined by the WSDL, and can be used to access the contents of the messages programatically (rather than taking the response as an XML document to be parsed separately).</p>
368<p>The class <a href="ndg\services\discovery\DiscoveryServiceClient.html">ndg.services.discovery.DiscoveryClient</a> makes use of this api in a simplistic way to:</p>
369<ul>
370  <li>parse an input XML message document and create a doSearchRequest message</li>
371  <li>generate an output XML message from the response </li>
372</ul>
373<p>Here's the code for the doSearch and doPresent methods of this client:</p>
374<pre>
375        /**
376         * Acts as proxy method for doSearch operation
377         * @param reqDocAsString String containing XML request doc (see WSDL for structure)
378         * @return String containing SearchReturn (see WSDL for structure)
379         */
380        public String doSearch(
381                String reqDocAsString
382        ) throws java.rmi.RemoteException, org.apache.xmlbeans.XmlException
383        {
384                discoveryserviceapi.DoSearchDocument reqDoc= discoveryserviceapi.DoSearchDocument.Factory.parse( reqDocAsString );
385                discoveryserviceapi.DoSearchReturnDocument resDoc= _service.doSearch( reqDoc );
386                return resDoc.toString();
387        }
388
389        /**
390         * Acts as proxy method for doPresent operation
391         * @param reqDocAsString String containing XML request doc (see WSDL for structure)
392         * @return String containing PresentReturn (see WSDL for structure)
393         */
394        public String doPresent(
395                String reqDocAsString
396        ) throws java.rmi.RemoteException, org.apache.xmlbeans.XmlException
397        {
398                discoveryserviceapi.DoPresentDocument reqDoc= discoveryserviceapi.DoPresentDocument.Factory.parse( reqDocAsString );
399                discoveryserviceapi.DoPresentReturnDocument resDoc= _service.doPresent( reqDoc );
400                return resDoc.toString();
401        }</pre>
402<p>To demonstrate the use of the helper classes, it's worth taking this example further. Package <a href="discoveryserviceapi/package-summary.html">discoveryserviceapi</a> contains classes corresponding to the names of the elements in the messages, defined in the WSDL. For example, if we need to extract the boolean value <code>&lt;status&gt;</code> (indicating whether there are results to collect), we can either:</p>
403<ul>
404  <li>Parse the returned <code>doSearchReturn</code> XML document and use XPath to extract the value of <code>/doSearchReturn/status</code>, or </li>
405  <li>Use the code below to process the response from the <code>doSearch</code> operation, and invoke the <code>getHits()</code> method of the <code>doSearchReturn</code> object </li>
406</ul>
407<pre>           
408        discoveryserviceapi.DoSearchReturnDocument resDoc= _service.doSearch( reqDoc );
409        // extract the value of status using helper method
410        boolean status = resDoc.getDoSearchReturn().getStatus();</pre>
411<p>This is first requesting a <code>doSearchReturn</code> object from the <code>resDoc</code>, then applying the <code>getStatus()</code> method to it. When applied to more complex tasks like iterating through the set of returned documents in a doPresent, this can approach be quite useful. Similarly, request documents can also be constructed programatically in this way.
412</BODY>
413</HTML>
Note: See TracBrowser for help on using the repository browser.