Changes between Version 63 and Version 64 of Discovery/DiscoveryWebServiceMEDIN


Ignore:
Timestamp:
02/03/10 15:20:31 (9 years ago)
Author:
sdonegan
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Discovery/DiscoveryWebServiceMEDIN

    v63 v64  
    264264    TOTAL number of hits returned  
    265265  Documents:: 
    266     parent element for <!DocumentId>, <!DocumentBrief> OR <!DocumentSummary> elements (as per choice in search request) containing returned results.  
     266    parent element for <!DocumentSimple>, <!DocumentBrief>, <!DocumentSummary> and <!DocumentFull> elements (as per choice in <!RecordDetail> within search request) containing returned results.  
    267267 
    268268A result where no hits were returned is shown below: 
    269269{{{ 
    270 <DoSearchReturn xmlns="urn:DiscoveryServiceAPI"> 
    271         <Status>false</Status> 
    272         <StatusMessage>Search was successful but generated no results.</StatusMessage> 
    273         <ResultId>0</ResultId> 
    274         <Hits>0</hits> 
    275 </DoSearchReturn> 
    276 }}} 
    277  
    278 A result where 2 hits were returned, with the <!RecordDetail> set to !DocumentId, is shown below: 
    279 {{{ 
    280 <DoSearchReturn xmlns="urn:DiscoveryServiceAPI"> 
    281         <Status>true</Status> 
    282         <StatusMessage>Search was successful.</StatusMessage> 
    283         <ResultId>0</ResultId> 
    284         <Hits>2</Hits> 
    285         <Documents> 
    286           <DocumentId>idForResult1GoesHere</DocumentId> 
    287           <DocumentId>idForResult2GoesHere</DocumentId> 
    288         </Documents> 
    289 </DoSearchReturn> 
    290 }}} 
    291  
    292 If <!DocumentBrief> is specified as the !RecordDetail, a <!DocumentBrief> element is returned for each result, as outlined in the doSearchResponeMessage, above. This contains the <!DocumentId> element, containing the id of the document, but is accompanied by the additional element <Title>, containing the title from the metadata record, and a set of <!OrderedField> elements corresponding to the <!OrderByField>s used in the search request. In other words, the requested ordering fields are returned alongside the results so that a client can display the content of those fields which contributed to the resulting record ordering. The purpose of this <!DocumentBrief> detail option is to enable clients to render a results list directly from the search response, without having immediately to invoke the doPresent operation to retrieve additional detail. 
     270<sch:DoSearchReturn xmlns:sch="http://medin.discovery.services.ndg/schema"> 
     271                        <sch:Status>true</sch:Status> 
     272                        <sch:StatusMessage>Search was successful but generated no results</sch:StatusMessage> 
     273                        <sch:ResultId>0</sch:ResultId> 
     274                        <sch:Hits>0</sch:Hits> 
     275</sch:DoSearchReturn> 
     276}}} 
     277 
     278A result where 2 hits were returned, with the <!RecordDetail> set to !DocumentSimple, is shown below: 
     279{{{ 
     280<sch:DoSearchReturn xmlns:sch="http://medin.discovery.services.ndg/schema"> 
     281                        <sch:Status>true</sch:Status> 
     282                        <sch:StatusMessage>Successful</sch:StatusMessage> 
     283                        <sch:ResultId>0</sch:ResultId> 
     284                        <sch:Hits>2</sch:Hits> 
     285                        <sch:Documents> 
     286                                <sch:DocumentSimple> 
     287                                        <sch:DocumentId>record1</sch:DocumentId> 
     288                                </sch:DocumentSimple> 
     289                                <sch:DocumentSimple> 
     290                                        <sch:DocumentId>record2</sch:DocumentId> 
     291                                </sch:DocumentSimple> 
     292                        </sch:Documents> 
     293</sch:DoSearchReturn> 
     294}}} 
     295 
     296If <!DocumentBrief> is specified as the !RecordDetail, a <!DocumentBrief> element is returned for each result, as outlined in the doSearchResponeMessage, above. This contains the <!DocumentId> element, containing the id of the document, but is accompanied by the additional element <Title>, containing the title from the metadata record, and a set of <!OrderedField> elements corresponding to the <!OrderByField>s used in the search request.  The element <!AdditionalInformation> holds further elements containing further information pertaining to the record in question.  In other words, the requested ordering fields are returned alongside the results so that a client can display the content of those fields which contributed to the resulting record ordering. The purpose of this <!DocumentBrief> detail option is to enable clients to render a results list directly from the search response, without having immediately to invoke the doPresent operation to retrieve additional detail. 
    293297 
    294298Similarly, if <!DocumentSummary> is specified as the recordDetail, a <!DocumentSummary> element is returned for each result, as outlined in the doSearchResponseMessage, above. In addition to the content added by the <!DocumentBrief> option, <!DocumentSummary> includes the metadata abstract, and temporal and spatial information. For the temporal and spatial components of this <!DocumentSummary> the schema reuses the structures used for the search request, hence the optional temporalOperator are spatialOperator elements are redundant (and will be omitted) from the return context, however the dateRangeTarget element is useful as a contextual reminder of what the returned date pertains to (temporal coverage of data, last revision date of data, or ingestion date of metadata, etc.). 
    295299 
    296 A corresponding <!DocumentFull> structure is used in the [#doPresentoperation doPresent operation] operation as the structure in which the document payload is returned. 
    297  
    298 === doPresent operation === 
     300Correspondingly the <!DocumentFull> element builds upon the <!DocumentBrief> and <!DocumentSummary> elements adding further information (including <!AdditionalInformation>) but importantly a <Document> element contains a CDATA representation of the original XML metadata with format corresponding to that chosen in <!MetadataFormat> (defaulting to MEDIN_2.3).  These 4 document types comprise a data type "Documents" which is dependant on the values supplied in <!RetrieveCriteria> and is also reused in the DoPresent operation. 
     301 
     302 
     303=== DoPresent operation === 
    299304 
    300305The doPresent operation provides a means of retrieving (presenting) one or more XML documents from the database. The doPresentRequest message is defined as follows (click image to enlarge):