Changes between Version 20 and Version 21 of Discovery/DiscoveryWebServiceMEDIN


Ignore:
Timestamp:
09/11/09 11:40:49 (10 years ago)
Author:
mpritcha
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Discovery/DiscoveryWebServiceMEDIN

    v20 v21  
    219219> Looking at these examples we might need to tidy up the capitalisation of elements in the schema & WSDL. 
    220220 
     221=== Paging : <start> and <howMany> ===  
     222The optional elements <start> and <howMany> 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 <start> is omitted, the default value used is 1 (i.e. the first record). If <howMany> is omitted, the default number of records returned is 30. 
    221223---- 
    222224Content below here not updated yet 
    223225---- 
    224  
    225 === Paging : <start> and <howMany> ===  
    226 The optional elements <start> and <howMany> 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 <start> is omitted, the default value used is 1 (i.e. the first record). If <howMany> is omitted, the default number of records returned is 30. 
    227  
    228226=== Ordering: <orderBy> and <orderByDirection> === 
    229 Ordering of the result set can be requested by setting <orderBy> to one of the valid values listed in the orderByFieldList accesible via the getList operation. Currently these are: 
     227Ordering of the result set can optionally be requested by providing an <orderBy> element containing one or more <orderByField>s each with an optional associated <orderByDirection> (default : descending). Available fields for use as an <orderByField> are listed in the [#orderByFieldsList orderByFieldList]. 
     228 
     229 
     230In addition, the direction of ordering (ascending or descending) can be specified. If omitted, the default direction is descending. 
     231 
     232=== Scope of search: <scope> === 
     233The optional <scope> 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 scopeList list accessible via the getList operation. 
     234If <scope> is omitted, the search is not restricted in this way. 
     235 
     236== Search results == 
     237The doSearchResponse message is defined in the WSDL as shown below: 
     238 
     239#![[Image(doSearchReturnSchema.png)]] 
     240 
     241The <doSearchReturn> element contains the following top-level elements: 
     242 
     243  status:: 
     244    true if successful AND number of hits > 0, false otherwise (designed so that a client need only proceed to parse the rest of the message if results were successfully returned)  
     245  statusMessage:: 
     246    Textual information regarding success / failure / errors  
     247  resultId:: 
     248    reserved for future use  
     249  hits:: 
     250    TOTAL number of hits returned  
     251  documents:: 
     252    parent element for array of <document> elements containing returned document IDs  
     253 
     254A typical search result was shown in the "Quick Start" section. A result where no hits were returned is shown below 
     255{{{ 
     256<doSearchReturn xmlns="urn:DiscoveryServiceAPI"> 
     257        <status>false</status> 
     258        <statusMessage>Search was successful but generated no results.</statusMessage> 
     259        <resultId>0</resultId> 
     260        <hits>0</hits> 
     261</doSearchReturn> 
     262}}} 
     263 
     264=== doPresent operation === 
     265 
     266The doPresent operation provides a means of retrieving (presenting) one or more XML documents from the database. The doPresentRequest message is defined as follows: 
     267 
     268#![[Image(doPresentSchema.png)]] 
     269 
     270One or more <document> elements should each contain the names of a document (in the form returned in the doSearchReturn message) to be retrieved. The optional <format> element should be populated with one of the supported format names as listed by the presentFormatList accessible via the [#getListoperation getList] operation. All documents returned by a single invocation of the doPresent operation are returned in the same format, i.e. the choice of presentFormat applies to the doPresent request and not individual documents. Currently-supported formats are: 
     271 
     272original  
     273Documents are returned unaltered, in the format in which they were harvested (via OAI-PMH) from the data provider. 
     274 
     275  DC:: 
     276    Dublin Core format  
     277  DIF:: 
     278    GCMD DIF format (version ??) 
     279  MDIP:: 
     280    Metadata format used by the Marine Data and Information Partnership 
     281  ISO19115:: 
     282    ISO19115 (Geographic Information: Metadata) encoded as ISO19139 XML  
     283 
     284For all formats except original, the following action is taken prior to returning the document: 
     285 
     286  * Check if the document exists in the discovery database in the requested format, and if so, return it unaltered  
     287  * Apply a conversion XQuery to create a new document in that format on-the-fly  
     288 
     289==== doPresent response ==== 
     290The doPresentResponse message is defined in the WSDL as follows: 
     291 
     292#![[Image(doPresentReturnSchema.png)]] 
     293 
     294The <doPresentReturn> element contains the following top-level elements: 
     295 
     296  <status>:: 
     297    true if there are any documents returned in the payload, false otherwise.  
     298  <statusMessage>:: 
     299    Textual information regarding success / failure / errors.  
     300  <documents>:: 
     301    If some documents have been successfully returned, a <documents> element is present and will contain a child <document> element for each document retrieved. In the case where some but not all documents are successfully returned, the <documents> element will contain populated <document> elements for the successfully-retrieved documents, but an empty <document> element for those where retrieval failed. If NO documents are successfully returned, however, then the <status> is set to false and no <documents> element is included in the doPresentResponse message. 
     302 
     303The <document> element, if present and populated, contains the retrieved document as an encapsulated string representation of the XML. Depending on the client used to display the payload document, it either appears contained within a <![CDATA[ ... ]]> construct, or as XML with the opening angle brackets "<" escaped as "&lt;". Most XML parsers should successfully parse the string to reconstruct the XML document, but it is returned in this form to avoid namespace issues.  
     304 
     305The following request / response sequence shows a successful doPresent operation: 
     306 
     307Request: 
     308{{{ 
     309(tbc) 
     310}}} 
     311 
     312Response: 
     313{{{ 
     314(tbc) 
     315}}} 
     316 
     317 
     318== Term Lists == 
     319 
     320=== termTargetList === 
     321 fullText:: 
     322   Target is a stored version of the original harvested XML metadata document 
     323 
     324 author:: 
     325   Target is the entry in the discovery index database corresponding to the author of the data described by the metadata. 
     326 
     327 parameter:: 
     328   Target is entries in the discovery index database corresponding to parameter keywords extracted from the metadata. 
     329 
     330MEDINTermTarget.1*:: 
     331   Target is entry in the discovery database corresponding to the '''MEDINTermTarget.1''' field in the MEDIN metadata format. (*It has been agreed that the search capability will be extended to support direct searching of a limited number of target fields within the MEDIN metadata format. List of fields currently to be confirmed by MEDIN). 
     332 
     333=== presentFormatList === 
     334=== orderByFieldList === 
    230335  textRelevance:: 
    231336    Ranking metric based on relevance of match to search term (metric derived by postgres text ranking function). 
     
    248353  discoveryIngestDate:: 
    249354    Date order based on the date of insertion of that record into the underlying database supporting the service.  Note that this differs from "datasetUpdateOrder" in that this records the actual date a record was placed in the database as opposed to the last edit date of that record. 
    250  
    251 In addition, the direction of ordering (ascending or descending) can be specified. If omitted, the default direction is descending. 
    252  
    253 === Scope of search: <scope> === 
    254 The optional <scope> 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 scopeList list accessible via the getList operation. 
    255 If <scope> is omitted, the search is not restricted in this way. 
    256  
    257 == Search results == 
    258 The doSearchResponse message is defined in the WSDL as shown below: 
    259  
    260 #![[Image(doSearchReturnSchema.png)]] 
    261  
    262 The <doSearchReturn> element contains the following top-level elements: 
    263  
    264   status:: 
    265     true if successful AND number of hits > 0, false otherwise (designed so that a client need only proceed to parse the rest of the message if results were successfully returned)  
    266   statusMessage:: 
    267     Textual information regarding success / failure / errors  
    268   resultId:: 
    269     reserved for future use  
    270   hits:: 
    271     TOTAL number of hits returned  
    272   documents:: 
    273     parent element for array of <document> elements containing returned document IDs  
    274  
    275 A typical search result was shown in the "Quick Start" section. A result where no hits were returned is shown below 
    276 {{{ 
    277 <doSearchReturn xmlns="urn:DiscoveryServiceAPI"> 
    278         <status>false</status> 
    279         <statusMessage>Search was successful but generated no results.</statusMessage> 
    280         <resultId>0</resultId> 
    281         <hits>0</hits> 
    282 </doSearchReturn> 
    283 }}} 
    284  
    285 === doPresent operation === 
    286  
    287 The doPresent operation provides a means of retrieving (presenting) one or more XML documents from the database. The doPresentRequest message is defined as follows: 
    288  
    289 #![[Image(doPresentSchema.png)]] 
    290  
    291 One or more <document> elements should each contain the names of a document (in the form returned in the doSearchReturn message) to be retrieved. The optional <format> element should be populated with one of the supported format names as listed by the presentFormatList accessible via the [#getListoperation getList] operation. All documents returned by a single invocation of the doPresent operation are returned in the same format, i.e. the choice of presentFormat applies to the doPresent request and not individual documents. Currently-supported formats are: 
    292  
    293 original  
    294 Documents are returned unaltered, in the format in which they were harvested (via OAI-PMH) from the data provider. 
    295  
    296   DC:: 
    297     Dublin Core format  
    298   DIF:: 
    299     GCMD DIF format (version ??) 
    300   MDIP:: 
    301     Metadata format used by the Marine Data and Information Partnership 
    302   ISO19115:: 
    303     ISO19115 (Geographic Information: Metadata) encoded as ISO19139 XML  
    304  
    305 For all formats except original, the following action is taken prior to returning the document: 
    306  
    307   * Check if the document exists in the discovery database in the requested format, and if so, return it unaltered  
    308   * Apply a conversion XQuery to create a new document in that format on-the-fly  
    309  
    310 ==== doPresent response ==== 
    311 The doPresentResponse message is defined in the WSDL as follows: 
    312  
    313 #![[Image(doPresentReturnSchema.png)]] 
    314  
    315 The <doPresentReturn> element contains the following top-level elements: 
    316  
    317   <status>:: 
    318     true if there are any documents returned in the payload, false otherwise.  
    319   <statusMessage>:: 
    320     Textual information regarding success / failure / errors.  
    321   <documents>:: 
    322     If some documents have been successfully returned, a <documents> element is present and will contain a child <document> element for each document retrieved. In the case where some but not all documents are successfully returned, the <documents> element will contain populated <document> elements for the successfully-retrieved documents, but an empty <document> element for those where retrieval failed. If NO documents are successfully returned, however, then the <status> is set to false and no <documents> element is included in the doPresentResponse message. 
    323  
    324 The <document> element, if present and populated, contains the retrieved document as an encapsulated string representation of the XML. Depending on the client used to display the payload document, it either appears contained within a <![CDATA[ ... ]]> construct, or as XML with the opening angle brackets "<" escaped as "&lt;". Most XML parsers should successfully parse the string to reconstruct the XML document, but it is returned in this form to avoid namespace issues.  
    325  
    326 The following request / response sequence shows a successful doPresent operation: 
    327  
    328 Request: 
    329 {{{ 
    330 (tbc) 
    331 }}} 
    332  
    333 Response: 
    334 {{{ 
    335 (tbc) 
    336 }}} 
    337  
    338  
    339 == Term Lists == 
    340  
    341 === termTargetList === 
    342  fullText:: 
    343    Target is a stored version of the original harvested XML metadata document 
    344  
    345  author:: 
    346    Target is the entry in the discovery index database corresponding to the author of the data described by the metadata. 
    347  
    348  parameter:: 
    349    Target is entries in the discovery index database corresponding to parameter keywords extracted from the metadata. 
    350  
    351 MEDINTermTarget.1*:: 
    352    Target is entry in the discovery database corresponding to the '''MEDINTermTarget.1''' field in the MEDIN metadata format. (*It has been agreed that the search capability will be extended to support direct searching of a limited number of target fields within the MEDIN metadata format. List of fields currently to be confirmed by MEDIN). 
    353  
    354 === presentFormatList === 
    355 === orderByFieldList === 
     355    MEDINTermTarget.1*:: 
     356      One of fields specified by MEDIN for use as a termTarget : it should be possible to configure these for use as orderByFields, too. 
     357 
    356358=== scopeList === 
    357359  MDIP::